Update Quick-Start-with-weed-mini.md

2026-09-20 13:30:46 +02:00 · 2026-05-02 21:02:34 -07:00
parent 6327373463
commit 5d9c0cb6b8
1 changed files with 39 additions and 79 deletions
@@ -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