diff --git a/Quick-Start-with-weed-mini.md b/Quick-Start-with-weed-mini.md index 4f67472..4d89363 100644 --- a/Quick-Start-with-weed-mini.md +++ b/Quick-Start-with-weed-mini.md @@ -52,27 +52,36 @@ For a typical single-node S3 setup, `weed mini` is the simpler choice — you ge ## Quick Start -### Basic Usage +Start a ready-to-use S3 object store with credentials and a pre-created bucket in one command: ```bash +AWS_ACCESS_KEY_ID=admin \ +AWS_SECRET_ACCESS_KEY=secret \ +S3_BUCKET=my-bucket \ weed mini -dir=/data ``` -This starts all services with the default configuration: -- Master UI: http://localhost:9333 -- Filer UI: http://localhost:8888 -- S3 Endpoint: http://localhost:8333 -- WebDAV: http://localhost:7333 -- Admin UI: http://localhost:23646 -- Volume Server: http://localhost:9340 - -### Custom Data Directory +That's it — the S3 endpoint is at http://localhost:8333, `my-bucket` already exists, and `admin`/`secret` are valid credentials. Test it: ```bash -weed mini -dir=/path/to/data +aws --endpoint-url http://localhost:8333 s3 ls s3://my-bucket/ ``` -### Custom Port +The same command also brings up: +- Master UI: http://localhost:9333 +- Volume Server: http://localhost:9340 +- Filer UI: http://localhost:8888 +- WebDAV: http://localhost:7333 +- Admin UI: http://localhost:23646 + +### What each piece does (and how to drop it) + +- **`-dir=/data`** — where data lives. Required. +- **`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`** — seed initial S3 credentials for the `mini` user. Omit them to start in unauthenticated "Allow All" mode (development only — see [Default S3 Access](#default-s3-access)). +- **`S3_BUCKET=my-bucket`** — pre-create this bucket on first start. Comma-separated list is accepted (`S3_BUCKET=raw,processed`). Idempotent on later starts. Equivalent to `-bucket=my-bucket` on the command line. Omit to skip bucket creation. +- **`S3_TABLE_BUCKET=iceberg-tables`** — same idea but creates an [S3 Tables](S3-Tables.md) (Iceberg) bucket. Comma-separated list also supported. Equivalent to `-tableBucket=iceberg-tables`. + +### Custom port ```bash weed mini -dir=/data -master.port=9444 -s3.port=8334 @@ -91,15 +100,15 @@ For more configuration details, see the **[[S3 Nginx Proxy]]** page. ## Run with Docker -The `chrislusf/seaweedfs` image runs `weed mini -dir=/data` by default, so no command arguments are required. - -### Simple `docker run` +The `chrislusf/seaweedfs` image runs `weed mini -dir=/data` by default, so the only thing you pass is the env vars (and a volume mount if you want data to survive restarts): ```bash docker run -d --name weed-mini \ -p 8333:8333 -p 8888:8888 -p 9333:9333 -p 23646:23646 \ + -v weed-data:/data \ -e AWS_ACCESS_KEY_ID=admin \ -e AWS_SECRET_ACCESS_KEY=secret \ + -e S3_BUCKET=my-bucket \ chrislusf/seaweedfs ``` @@ -109,31 +118,18 @@ Exposed ports: - `9333` — Master UI - `23646` — Admin UI -`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` seed the initial IAM credentials for the `mini` user at startup. Without them the S3 gateway starts in "Allow All" mode (see [Default S3 Access](#default-s3-access)). +Drop any of the env vars to skip that piece (no `S3_BUCKET` → no bucket created; no AWS keys → "Allow All" mode). Drop `-v weed-data:/data` if you don't need data to persist across container restarts. -### Persisting data across restarts +### Manage buckets after startup -Mount a named volume (or a host path) at `/data`: +Use the built-in `weed shell` — it talks directly to the master, so no AWS CLI or credentials needed: ```bash -docker run -d --name weed-mini \ - -p 8333:8333 \ - -v weed-data:/data \ - -e AWS_ACCESS_KEY_ID=admin \ - -e AWS_SECRET_ACCESS_KEY=secret \ - chrislusf/seaweedfs -``` - -### Create the first bucket - -Use the built-in `weed shell` — it talks directly to the master, so there's no AWS CLI to install and no credentials to set up: - -```bash -docker exec -i weed-mini weed shell <<< "s3.bucket.create -name my-bucket" +docker exec -i weed-mini weed shell <<< "s3.bucket.create -name another-bucket" docker exec -i weed-mini weed shell <<< "s3.bucket.list" ``` -For an interactive prompt, run `docker exec -it weed-mini weed shell` and type `help` to see all commands (`s3.bucket.create`, `s3.bucket.list`, `s3.bucket.delete`, etc.). +For an interactive prompt: `docker exec -it weed-mini weed shell`, then `help`. ### Use as a GitHub Actions service container @@ -151,6 +147,7 @@ jobs: env: AWS_ACCESS_KEY_ID: admin AWS_SECRET_ACCESS_KEY: secret + S3_BUCKET: my-bucket env: AWS_ACCESS_KEY_ID: admin AWS_SECRET_ACCESS_KEY: secret @@ -166,60 +163,17 @@ jobs: done echo "S3 endpoint did not become ready" >&2 exit 1 - - name: Create the test bucket - run: aws --endpoint-url "$S3_ENDPOINT" s3 mb s3://my-bucket - run: ./run-tests.sh ``` -## S3 Credentials Setup - -### Option 1: Environment Variables (Recommended) - -Set AWS credentials before starting: - -```bash -export AWS_ACCESS_KEY_ID=your-access-key -export AWS_SECRET_ACCESS_KEY=your-secret-key -export S3_ENDPOINT=http://localhost:8333 -weed mini -dir=/data -``` - -The initial IAM config will be created automatically for the `mini` user with these credentials. - -### Option 2: Admin UI - -1. Start `weed mini` -2. Open http://localhost:23646 in your browser -3. Navigate to the IAM/Credentials section -4. Create new identities with S3 credentials - ## Default S3 Access -By default, the SeaweedFS S3 gateway starts in **"Allow All" mode** if no S3 credentials are configured. This is designed for maximum ease of use in development and testing environments, and it applies to all S3 instances, including `weed mini`. +The S3 gateway starts in **"Allow All" mode** when no credentials are configured — convenient for development, but not what you want in production. The Quick Start command above seeds credentials via `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` so authentication is enabled from the first request. - **No credentials configured**: All S3 operations are allowed without authentication. -- **Credentials added**: As soon as *any* credentials are configured (either initially via flags/env vars or dynamically via the Admin UI/Shell), **authentication is automatically enabled** and all requests will then require valid credentials. +- **Credentials added**: As soon as *any* credentials are configured (env vars at startup, the Admin UI at http://localhost:23646, or `weed shell`), authentication switches on and all requests must be signed. -### Enabling Authentication - -To enable authentication for `weed mini`, use one of the following methods: - -1. **Environment Variables**: Set `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` before starting. - -```bash -export AWS_ACCESS_KEY_ID=any -export AWS_SECRET_ACCESS_KEY=any -export S3_ENDPOINT=http://localhost:8333 -weed mini -dir=/data -``` - -2. **Config File**: Use the `-s3.config` flag with a JSON credentials file. - -```bash -weed mini -dir=/data -s3.config=s3.config -``` - -3. **Dynamic Configuration**: Start normally, then add users through the **Admin UI** or **weed shell**. The server will automatically switch from "Allow All" to "Authentication Required" mode. +For larger credential sets, use a JSON file with `-s3.config=s3.config` instead of env vars. --- @@ -279,6 +233,12 @@ weed mini -dir=/data -s3.port=8334 # Custom IAM config file weed mini -dir=/data -s3.iam.config=/path/to/iam.json + +# Pre-create one or more S3 buckets on startup if they do not already exist +weed mini -dir=/data -bucket=raw,processed + +# Pre-create an S3 Tables (Iceberg) bucket +weed mini -dir=/data -tableBucket=iceberg-tables ``` ## Growing Into a Small Cluster