diff --git a/content/de/installation/container/docker.md b/content/de/installation/container/docker.md index 8469df29..c88d6100 100644 --- a/content/de/installation/container/docker.md +++ b/content/de/installation/container/docker.md @@ -1,17 +1,23 @@ --- title: "Docker" -description: "Run a single-node RustFS instance with Docker and persistent container storage." +description: "Run RustFS with Docker: single-node setup, host-directory permissions, Docker Compose, TLS, and multi-node deployment." --- -Use the official RustFS image to start a single-node instance with persistent storage. You need a working Docker Engine and permission to run containers. +This page covers running the official RustFS image with Docker: a single-node instance with persistent storage, host-directory permissions for the non-root container user, Docker Compose with optional observability services, TLS, and a multi-node deployment. You need a working Docker Engine and permission to run containers. -## 1. Pull the image +## 1. Prerequisites + +* Docker Engine (≥ 20.10) installed and able to pull images and run containers normally +* Host ports 9000 (S3 API) and 9001 (Console) available, or consistent with your custom ports +* If you bind-mount a host directory, the directory owner must match the container user — see [Bind-mount a host directory](#bind-mount-a-host-directory) + +## 2. Pull the image ```bash docker pull rustfs/rustfs:latest ``` -## 2. Create persistent storage +## 3. Create persistent storage Create a named volume so object data remains available when you replace the container: @@ -19,7 +25,7 @@ Create a named volume so object data remains available when you replace the cont docker volume create rustfs-data ``` -## 3. Start RustFS +## 4. Start RustFS Replace the credential placeholders before running the container: @@ -47,7 +53,33 @@ Set unique `RUSTFS_ACCESS_KEY` and `RUSTFS_SECRET_KEY` environment variables bef ::: -## 4. Verify the deployment +### Environment variables or command-line flags + +The example above configures RustFS with environment variables. You can pass the same settings as command-line flags instead; when both are present, command-line flags win: + +```bash +docker run -d \ + --name rustfs \ + -p 9000:9000 \ + -p 9001:9001 \ + -v rustfs-data:/data \ + rustfs/rustfs:latest \ + --access-key "" \ + --secret-key "" \ + --address :9000 \ + --console-enable \ + /data +``` + +## 5. Bind-mount a host directory + +The named volume above needs no extra setup. If you mount a host directory instead (`-v /path/on/host:/data`), keep in mind that the container runs as non-root user `rustfs` with id `10001`. Make the host directory owned by `10001`, otherwise you will encounter permission denied errors: + +```bash +chown -R 10001:10001 /path/to/host_directory +``` + +## 6. Verify the deployment Check the container and the S3 API health endpoint: @@ -58,8 +90,106 @@ curl --fail http://localhost:9000/health The S3 API is available at `http://localhost:9000`, and the Console is available at `http://localhost:9001`. +## Docker Compose + +The RustFS repository ships a [`docker-compose.yml`](https://github.com/rustfs/rustfs/blob/main/docker-compose.yml) that includes `grafana`, `prometheus`, `otel-collector`, and `jaeger` services, mainly for observability. To deploy RustFS together with these services, clone the [RustFS code repository](https://github.com/rustfs/rustfs) locally: + +```bash +git clone https://github.com/rustfs/rustfs.git +``` + +Run the command from the repository root: + +```bash +docker compose --profile observability up -d +``` + +The compose file uses an initialization container to grant the correct access rights to `rustfs`: the `rustfs_perms` service below changes the ownership of the mounted volumes to `10001` before `rustfs` starts, using `depends_on` to wait for it to complete. To keep logs persistent and accessible, the host log directory is mapped to the container's `/var/log/rustfs/` path: + +```yaml title="docker-compose.yml" + services: + # grant the necessary permissions to RUSTFS volumes path + rustfs_perms: + image: alpine + user: root + volumes: + - /path/to/host_directory/volumes:/fix_path + command: chown -R 10001:10001 /fix_path + + rustfs: + image: rustfs/rustfs:latest + depends_on: + rustfs_perms: + condition: service_completed_successfully + volumes: + - /path/to_host_directory/volumes/data:/data + - /path/to_host_directory/volumes/logs:/var/log/rustfs/ + environment: + - RUSTFS_ADDRESS=":9000" + - RUSTFS_CONSOLE_ADDRESS=":9001" + - RUSTFS_CONSOLE_ENABLE=true + - RUSTFS_OBS_LOGGER_LEVEL=error + - RUSTFS_OBS_LOG_DIRECTORY="/var/log/rustfs/" + + # ... other configurations +``` + +If you only want RustFS without Grafana, Prometheus, and the other observability services, start just the `rustfs` service (the compose file marks the collector dependency as optional): + +```bash +docker compose -f docker-compose.yml up -d rustfs +``` + +This starts only the `rustfs-server` container. Whether you start only `rustfs-server` or the full stack, the S3 API is served at `http://localhost:9000`, and the RustFS Console is at `http://localhost:9001`. Open the Console in a browser and log in with the access key and secret key you configured above. Generate a strong secret with, for example, `openssl rand -base64 24`, and never ship the placeholder values to production. + +For Docker Compose, define unique `RUSTFS_ACCESS_KEY` and `RUSTFS_SECRET_KEY` values in the `rustfs` service environment or in the environment file used for variable substitution, then recreate the service with `docker compose up -d rustfs`. + +## Multi-node deployment + +Docker's default bridge networking does not support multi-node deployments. Use `--network host` so each container can communicate directly with other nodes. + +Run the following on **each node**: + +```bash +docker run -d \ + --name rustfs \ + --network host \ + -v /mnt/rustfs/data:/data \ + -e RUSTFS_ACCESS_KEY="" \ + -e RUSTFS_SECRET_KEY="" \ + -e RUSTFS_ADDRESS=":9000" \ + -e RUSTFS_CONSOLE_ADDRESS=":9001" \ + -e RUSTFS_CONSOLE_ENABLE=true \ + -e RUSTFS_OBS_LOGGER_LEVEL=error \ + -e RUSTFS_OBS_LOG_DIRECTORY="/var/log/rustfs/" \ + -e RUSTFS_VOLUMES="http://node{1...4}:9000/data/rustfs{0...3}" \ + rustfs/rustfs:latest +``` + +Add the entries to `/etc/hosts` on **every** node: + +```ini title="/etc/hosts" +192.168.1.1 node1 +192.168.1.2 node2 +192.168.1.3 node3 +192.168.1.4 node4 +``` + +## TLS configuration + +If [using TLS](../../integration/tls-configured.md), mount the certificate directory and point RustFS at it: + +```bash +-v /path/to/certs:/certs \ +-e RUSTFS_TLS_PATH=/certs \ +``` + +## Before production + +Work through the [Pre-Installation Checklists](../requirement/checklists/index.md) — hardware, network, software, and security — before deploying to production. Use a multi-node deployment architecture, [enable TLS encrypted communication](../../integration/tls-configured.md), configure a log rotation strategy, and set up a regular backup strategy. + ## Next steps - [RustFS Console](/administration/console) - [Configure an S3 client](../../developer/examples/aws-cli.md) -- [TLS configuration](../../integration/tls-configured.md) \ No newline at end of file +- [TLS configuration](../../integration/tls-configured.md) diff --git a/content/de/installation/container/index.md b/content/de/installation/container/index.md new file mode 100644 index 00000000..4ee47b47 --- /dev/null +++ b/content/de/installation/container/index.md @@ -0,0 +1,25 @@ +--- +title: "Container" +description: "Run the official RustFS container image with Docker or Podman." +--- + +RustFS is a high-performance, S3-compatible open-source distributed object storage system. In single-node single-disk (SNSD) deployment mode, the backend uses zero erasure coding without additional data redundancy, which makes it suitable for local testing and small-scale scenarios. The official RustFS image packages the RustFS binary and its runtime environment into a container, so you can start a service with a single command and persistent storage. + +The container runs as non-root user `rustfs` with id `10001`, so a bind-mounted host directory must be owned by `10001` to avoid permission denied errors. + +## Container runtimes + +- [Docker](./docker.md): run a single-node instance with persistent storage, then extend it with Docker Compose, TLS, and multi-node networking. +- [Podman](./podman.md): run the same image in a daemonless workflow. + +:::note[Directory permissions] + +If you mount a host directory into the container with `-v`, make sure the owner of the host directory is `10001`: + +```bash +chown -R 10001:10001 /path/to/host_directory +``` + +::: + +For Kubernetes deployments, see the [Helm chart](/installation/cloud-native/helm-chart) or the [Operator](/installation/cloud-native/operator) instead. diff --git a/content/de/installation/container/index.mdx b/content/de/installation/container/index.mdx deleted file mode 100644 index 27ed2b35..00000000 --- a/content/de/installation/container/index.mdx +++ /dev/null @@ -1,317 +0,0 @@ ---- -title: "Installing RustFS with Docker" -description: "RustFS Docker deployment." ---- - -RustFS is a high-performance, S3-compatible open-source distributed object storage system. In single-node single-disk (SNSD) deployment mode, the backend uses zero erasure coding without additional data redundancy, suitable for local testing and small-scale scenarios. -This article is based on RustFS official Linux binary packages, packaging RustFS and its runtime environment into containers through custom Dockerfile, and configuring data volumes and environment variables for one-click service startup. - ---- - -## 1. Prerequisites - -1. **Host Requirements** - - * Docker installed (≥ 20.10) and able to pull images and run containers normally - * Local path `/mnt/rustfs/data` (or custom path) for mounting object data - * [`rc`](/operations/rc) installed on the administration host for the verification workflow -2. **Network and Firewall** - - * Ensure host ports 9000 (S3 API) and 9001 (Console) are open to external access (or consistent with custom ports) - -3. **Directory Permissions** - - * The RustFS container runs as non-root user `rustfs` with id `10001`. If you run docker with `-v` to mount a host directory into the container, make sure the owner of the host directory is `10001`, otherwise you will encounter permission denied errors. Run `chown -R 10001:10001 /path/to/host_directory` to grant the necessary permissions. - ---- - -## 2. Pull the RustFS Official Image - -Pull the official image (Alpine-based) from Docker Hub: - -```bash -docker pull rustfs/rustfs -``` - ---- - - - -## 3. Run RustFS Container - -RustFS SNSD Docker running method, combining the above image and configuration, execute: - -```bash - docker run -d \ - --name rustfs_local \ - -p 9000:9000 \ - -p 9001:9001 \ - -v /mnt/rustfs/data:/data \ - rustfs/rustfs:latest \ - /data -``` - -Parameter descriptions: - -* `-p 9000:9000`: Map host port 9000 to container -* `-v /mnt/rustfs/data:/data`: Mount data volume -* `--name rustfs_local`: Custom container name -* `-d`: Run in background - ---- - -### Complete Configuration Example - -Configuration can be passed as environment variables (recommended) or as command-line flags — pick one style; when both are present, command-line flags win. The volume path (`/data`) always comes last. - - - - -```bash {7,8} -# Use a unique access key and a strong, random secret (e.g. openssl rand -base64 24) -docker run -d \ - --name rustfs \ - -p 9000:9000 \ - -p 9001:9001 \ - -v /mnt/rustfs/data:/data \ - -e RUSTFS_ACCESS_KEY="" \ - -e RUSTFS_SECRET_KEY="" \ - -e RUSTFS_ADDRESS=":9000" \ - -e RUSTFS_CONSOLE_ADDRESS=":9001" \ - -e RUSTFS_CONSOLE_ENABLE=true \ - -e RUSTFS_OBS_LOGGER_LEVEL=error \ - -e RUSTFS_OBS_LOG_DIRECTORY="/var/log/rustfs/" \ - rustfs/rustfs:latest \ - /data -``` - - - - -```bash {8,9} -# Use a unique access key and a strong, random secret (e.g. openssl rand -base64 24) -docker run -d \ - --name rustfs \ - -p 9000:9000 \ - -p 9001:9001 \ - -v /mnt/rustfs/data:/data \ - rustfs/rustfs:latest \ - --access-key "" \ - --secret-key "" \ - --address :9000 \ - --console-enable \ - /data -``` - - - - -### Common Configuration Combinations - -1. **Basic Configuration**: - ```bash - docker run -d \ - -p 9000:9000 \ - -p 9001:9001 \ - -v /mnt/data:/data \ - rustfs/rustfs:latest \ - /data - ``` - -2. **Enable Console**: - ```bash - docker run -d \ - -p 9000:9000 \ - -p 9001:9001 \ - -v /mnt/data:/data \ - -e RUSTFS_ADDRESS=":9000" \ - -e RUSTFS_CONSOLE_ADDRESS=":9001" \ - -e RUSTFS_CONSOLE_ENABLE=true \ - -e RUSTFS_OBS_LOGGER_LEVEL=error \ - -e RUSTFS_OBS_LOG_DIRECTORY="/var/log/rustfs/" \ - rustfs/rustfs:latest \ - --console-enable \ - /data - ``` - -3. **Custom Authentication Keys**: - ```bash - # Use a unique access key and a strong, random secret (e.g. openssl rand -base64 24) - docker run -d \ - -p 9000:9000 \ - -p 9001:9001 \ - -v /mnt/data:/data \ - -e RUSTFS_ACCESS_KEY="" \ - -e RUSTFS_SECRET_KEY="" \ - rustfs/rustfs:latest \ - --access-key "" \ - --secret-key "" \ - /data - ``` - -### Important Notes - -1. Port mapping must correspond: - - Service port defaults to 9000 (`-p 9000:9000`) - -2. Data volumes must be persistent: - - `-v /host/path:/container/path` - -3. Environment variables and command line parameters can be mixed, but command line parameters have higher priority - -4. If [using TLS](../../integration/tls-configured.md), additional certificate path mounting is needed: - - ```bash - -v /path/to/certs:/certs \ - -e RUSTFS_TLS_PATH=/certs \ - ``` - -### Docker Compose Installation - -RustFS officially provides a Docker Compose installation method. The [`docker-compose.yml`](https://github.com/rustfs/rustfs/blob/main/docker-compose.yml) file includes multiple services, such as `grafana`, `prometheus`, `otel-collector`, and `jaeger`, mainly for observability. If you want to deploy these services together, clone the [RustFS code repository](https://github.com/rustfs/rustfs) locally, - -```bash -git clone https://github.com/rustfs/rustfs.git -``` - -Running the command under root directory, - -```bash -docker compose --profile observability up -d -``` - -Providing the necessary permissions. An initialization container is necessary to grant the correct access rights to rustfs using the `depends_on` keyword. In the example below the `rustfs_perms` service is added to the `docker-compose.yml` to handle this. To ensure logs are persisted and accessible, we map the host log directory to the container's `/var/log/rustfs/` path - -```yaml title="docker-compose.yml" - services: - # grant the necessary permissions to RUSTFS volumes path - rustfs_perms: - image: alpine - user: root - volumes: - - /path/to/host_directory/volumes:/fix_path - command: chown -R 10001:10001 /fix_path - - rustfs: - image: rustfs/rustfs:latest - depends_on: - rustfs_perms: - condition: service_completed_successfully - volumes: - - /path/to_host_directory/volumes/data:/data - - /path/to_host_directory/volumes/logs:/var/log/rustfs/ - environment: - - RUSTFS_ADDRESS=":9000" - - RUSTFS_CONSOLE_ADDRESS=":9001" - - RUSTFS_CONSOLE_ENABLE=true - - RUSTFS_OBS_LOGGER_LEVEL=error - - RUSTFS_OBS_LOG_DIRECTORY="/var/log/rustfs/" - - # ... other configurations -``` - -Started containers is as below, - -```text -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -c13c23fe3d9d rustfs/rustfs:latest "/entrypoint.sh rust…" 6 seconds ago Up 5 seconds (health: starting) 0.0.0.0:9000-9001->9000-9001/tcp, :::9000-9001->9000-9001/tcp rustfs-server -e3f4fc4a83a2 grafana/grafana:latest "/run.sh" 7 seconds ago Up 5 seconds 0.0.0.0:3000->3000/tcp, :::3000->3000/tcp grafana -71ef1b8212cf prom/prometheus:latest "/bin/prometheus --c…" 7 seconds ago Up 5 seconds 0.0.0.0:9090->9090/tcp, :::9090->9090/tcp prometheus -e7db806b2d6f jaegertracing/all-in-one:latest "/go/bin/all-in-one-…" 7 seconds ago Up 5 seconds 4317-4318/tcp, 9411/tcp, 0.0.0.0:14250->14250/tcp, :::14250->14250/tcp, 14268/tcp, 0.0.0.0:16686->16686/tcp, :::16686->16686/tcp jaeger -1897830a2f1e otel/opentelemetry-collector-contrib:latest "/otelcol-contrib --…" 7 seconds ago Up 5 seconds 0.0.0.0:4317-4318->4317-4318/tcp, :::4317-4318->4317-4318/tcp, 0.0.0.0:8888-8889->8888-8889/tcp, :::8888-8889->8888-8889/tcp, 55679/tcp otel-collector -``` - -If you only want to install RustFS without Grafana, Prometheus, and the other observability services, start just the `rustfs` service (the compose file marks the collector dependency as optional): - -```bash -docker compose -f docker-compose.yml up -d rustfs -``` - -This way will only install and start `rustfs-server` service, namely rustfs container, - -```text -docker ps -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -e07121ecdd39 rustfs/rustfs:latest "/entrypoint.sh rust…" 2 seconds ago Up 1 second (health: starting) 0.0.0.0:9000-9001->9000-9001/tcp, :::9000-9001->9000-9001/tcp rustfs-server -``` - -Whether you start only the `rustfs-server` or together with observability services, the S3 API is served at `http://localhost:9000`, and the RustFS Console is at `http://localhost:9001` — open it in a browser and log in with the access key and secret key you configured above (the `` / `` placeholders). Generate a strong secret with, for example, `openssl rand -base64 24`, and never ship the placeholder values to production. - -:::warning[Set container credentials immediately] - -Set unique `RUSTFS_ACCESS_KEY` and `RUSTFS_SECRET_KEY` environment variables before exposing RustFS to a network. Do not use the well-known `rustfsadmin` value for either credential. For `docker run`, pass both values with `-e`. For Docker Compose, define both variables in the `rustfs` service environment or in the environment file used for variable substitution, then recreate the service with `docker compose up -d rustfs`. - -::: - -## 4. Verification and Access - -1. **View Container Status and Logs:** - - ```bash - docker logs rustfs_local - ``` - - Logs should show successful service startup and listening on port 9000. - -2. **Test S3 API:** - - Use `rc` to verify the S3 API: - - ```bash - # Use a unique access key and a strong, random secret (e.g. openssl rand -base64 24) - rc alias set rustfs http://localhost:9000 - rc bucket create rustfs/my-bucket - rc bucket list rustfs/ - ``` - - If buckets can be successfully created and listed, deployment is effective. - -## 5. Multiple Nodes - -Dockers default bridge networking does not support multi-node deployments. Use `--network host` so each container can communicate directly with other nodes. - -Run the following on **each node** - -```bash -# Use a unique access key and a strong, random secret (e.g. openssl rand -base64 24) -docker run -d \ - --name rustfs \ - --network host \ - -v /mnt/rustfs/data:/data \ - -e RUSTFS_ACCESS_KEY="" \ - -e RUSTFS_SECRET_KEY="" \ - -e RUSTFS_ADDRESS=":9000" \ - -e RUSTFS_CONSOLE_ADDRESS=":9001" \ - -e RUSTFS_CONSOLE_ENABLE=true \ - -e RUSTFS_OBS_LOGGER_LEVEL=error \ - -e RUSTFS_OBS_LOG_DIRECTORY="/var/log/rustfs/" \ - -e RUSTFS_VOLUMES="http://node{1...4}:9000/data/rustfs{0...3}" \ - rustfs/rustfs:latest -``` - -Add the entries to `/etc/hosts` on **every** node: -```ini title="/etc/hosts" -192.168.1.1 node1 -192.168.1.2 node2 -192.168.1.3 node3 -192.168.1.4 node4 -``` - -## 6. Other Recommendations - -1. Production Environment Recommendations: -- Use multi-node deployment architecture -- [Enable TLS encrypted communication](../../integration/tls-configured.md) -- Configure log rotation strategy -- Set up regular backup strategy - -2. Storage Recommendations: -- Use local SSD/NVMe storage -- Avoid using network file systems (NFS) -- Ensure storage directory exclusive access - ---- - -## Summary - -This article explains how to deploy RustFS using Docker with best practices, starting with a single-node single-disk (SNSD) setup and then extending to a multi-node deployment option. diff --git a/content/de/installation/container/podman.md b/content/de/installation/container/podman.md index 5c478328..9ce2a6fc 100644 --- a/content/de/installation/container/podman.md +++ b/content/de/installation/container/podman.md @@ -19,6 +19,16 @@ Create a named volume so object data remains available when you replace the cont podman volume create rustfs-data ``` +:::note[Bind-mounting a host directory] + +The named volume above needs no extra setup. If you bind-mount a host directory instead, keep in mind that the container runs as non-root user `rustfs` with id `10001`. Make the host directory owned by `10001`, otherwise you will encounter permission denied errors: + +```bash +chown -R 10001:10001 /path/to/host_directory +``` + +::: + ## 3. Start RustFS Replace the credential placeholders before running the container: @@ -61,4 +71,4 @@ The S3 API is available at `http://localhost:9000`, and the Console is available - [RustFS Console](/administration/console) - [Configure an S3 client](../../developer/examples/aws-cli.md) -- [TLS configuration](../../integration/tls-configured.md) \ No newline at end of file +- [TLS configuration](../../integration/tls-configured.md) diff --git a/content/de/installation/index.md b/content/de/installation/index.md index e7985e53..4d8361f5 100644 --- a/content/de/installation/index.md +++ b/content/de/installation/index.md @@ -18,7 +18,7 @@ After installation, set unique values for `RUSTFS_ACCESS_KEY` and `RUSTFS_SECRET | Your goal | Recommended path | Guide | | - | - | - | -| Try RustFS on a local machine | One-command install script, or a container | [Linux Quick Start](./linux/quick-start.md) · [Container](./container/index.mdx) | +| Try RustFS on a local machine | One-command install script, or a container | [Linux Quick Start](./linux/quick-start.md) · [Container](./container/index.md) | | Single-server production | SNSD (one disk) or SNMD (multiple disks) | [Installing RustFS on Linux](./linux/index.md) | | Multi-server production cluster | MNMD, after completing the production checklists | [Multiple Node Multiple Disk](./linux/multiple-node-multiple-disk.md) · [Checklists](./requirement/checklists/index.md) | | Kubernetes / cloud-native | Container orchestration deployment | [Cloud Native](./cloud-native/index.md) | diff --git a/content/de/installation/linux/quick-start.md b/content/de/installation/linux/quick-start.md index a43b7ef0..c72007b7 100644 --- a/content/de/installation/linux/quick-start.md +++ b/content/de/installation/linux/quick-start.md @@ -88,5 +88,5 @@ The quick install runs RustFS in **Single Node Single Disk (SNSD)** mode — zer - [Single Node Single Disk (SNSD)](./single-node-single-disk.md) — dev and small workloads - [Single Node Multiple Disk (SNMD)](./single-node-multiple-disk.md) — disk-level fault tolerance on one machine - [Multiple Node Multiple Disk (MNMD)](./multiple-node-multiple-disk.md) — production-grade availability and scale, with the [pre-installation checklists](../requirement/checklists/index.md) -- **Prefer containers?** — [Install with a container](../container/index.mdx) +- **Prefer containers?** — [Install with a container](../container/index.md) - **Connect your application** — [SDKs and examples](../../developer/sdk/index.md) diff --git a/content/en/installation/container/docker.md b/content/en/installation/container/docker.md index 8469df29..c88d6100 100644 --- a/content/en/installation/container/docker.md +++ b/content/en/installation/container/docker.md @@ -1,17 +1,23 @@ --- title: "Docker" -description: "Run a single-node RustFS instance with Docker and persistent container storage." +description: "Run RustFS with Docker: single-node setup, host-directory permissions, Docker Compose, TLS, and multi-node deployment." --- -Use the official RustFS image to start a single-node instance with persistent storage. You need a working Docker Engine and permission to run containers. +This page covers running the official RustFS image with Docker: a single-node instance with persistent storage, host-directory permissions for the non-root container user, Docker Compose with optional observability services, TLS, and a multi-node deployment. You need a working Docker Engine and permission to run containers. -## 1. Pull the image +## 1. Prerequisites + +* Docker Engine (≥ 20.10) installed and able to pull images and run containers normally +* Host ports 9000 (S3 API) and 9001 (Console) available, or consistent with your custom ports +* If you bind-mount a host directory, the directory owner must match the container user — see [Bind-mount a host directory](#bind-mount-a-host-directory) + +## 2. Pull the image ```bash docker pull rustfs/rustfs:latest ``` -## 2. Create persistent storage +## 3. Create persistent storage Create a named volume so object data remains available when you replace the container: @@ -19,7 +25,7 @@ Create a named volume so object data remains available when you replace the cont docker volume create rustfs-data ``` -## 3. Start RustFS +## 4. Start RustFS Replace the credential placeholders before running the container: @@ -47,7 +53,33 @@ Set unique `RUSTFS_ACCESS_KEY` and `RUSTFS_SECRET_KEY` environment variables bef ::: -## 4. Verify the deployment +### Environment variables or command-line flags + +The example above configures RustFS with environment variables. You can pass the same settings as command-line flags instead; when both are present, command-line flags win: + +```bash +docker run -d \ + --name rustfs \ + -p 9000:9000 \ + -p 9001:9001 \ + -v rustfs-data:/data \ + rustfs/rustfs:latest \ + --access-key "" \ + --secret-key "" \ + --address :9000 \ + --console-enable \ + /data +``` + +## 5. Bind-mount a host directory + +The named volume above needs no extra setup. If you mount a host directory instead (`-v /path/on/host:/data`), keep in mind that the container runs as non-root user `rustfs` with id `10001`. Make the host directory owned by `10001`, otherwise you will encounter permission denied errors: + +```bash +chown -R 10001:10001 /path/to/host_directory +``` + +## 6. Verify the deployment Check the container and the S3 API health endpoint: @@ -58,8 +90,106 @@ curl --fail http://localhost:9000/health The S3 API is available at `http://localhost:9000`, and the Console is available at `http://localhost:9001`. +## Docker Compose + +The RustFS repository ships a [`docker-compose.yml`](https://github.com/rustfs/rustfs/blob/main/docker-compose.yml) that includes `grafana`, `prometheus`, `otel-collector`, and `jaeger` services, mainly for observability. To deploy RustFS together with these services, clone the [RustFS code repository](https://github.com/rustfs/rustfs) locally: + +```bash +git clone https://github.com/rustfs/rustfs.git +``` + +Run the command from the repository root: + +```bash +docker compose --profile observability up -d +``` + +The compose file uses an initialization container to grant the correct access rights to `rustfs`: the `rustfs_perms` service below changes the ownership of the mounted volumes to `10001` before `rustfs` starts, using `depends_on` to wait for it to complete. To keep logs persistent and accessible, the host log directory is mapped to the container's `/var/log/rustfs/` path: + +```yaml title="docker-compose.yml" + services: + # grant the necessary permissions to RUSTFS volumes path + rustfs_perms: + image: alpine + user: root + volumes: + - /path/to/host_directory/volumes:/fix_path + command: chown -R 10001:10001 /fix_path + + rustfs: + image: rustfs/rustfs:latest + depends_on: + rustfs_perms: + condition: service_completed_successfully + volumes: + - /path/to_host_directory/volumes/data:/data + - /path/to_host_directory/volumes/logs:/var/log/rustfs/ + environment: + - RUSTFS_ADDRESS=":9000" + - RUSTFS_CONSOLE_ADDRESS=":9001" + - RUSTFS_CONSOLE_ENABLE=true + - RUSTFS_OBS_LOGGER_LEVEL=error + - RUSTFS_OBS_LOG_DIRECTORY="/var/log/rustfs/" + + # ... other configurations +``` + +If you only want RustFS without Grafana, Prometheus, and the other observability services, start just the `rustfs` service (the compose file marks the collector dependency as optional): + +```bash +docker compose -f docker-compose.yml up -d rustfs +``` + +This starts only the `rustfs-server` container. Whether you start only `rustfs-server` or the full stack, the S3 API is served at `http://localhost:9000`, and the RustFS Console is at `http://localhost:9001`. Open the Console in a browser and log in with the access key and secret key you configured above. Generate a strong secret with, for example, `openssl rand -base64 24`, and never ship the placeholder values to production. + +For Docker Compose, define unique `RUSTFS_ACCESS_KEY` and `RUSTFS_SECRET_KEY` values in the `rustfs` service environment or in the environment file used for variable substitution, then recreate the service with `docker compose up -d rustfs`. + +## Multi-node deployment + +Docker's default bridge networking does not support multi-node deployments. Use `--network host` so each container can communicate directly with other nodes. + +Run the following on **each node**: + +```bash +docker run -d \ + --name rustfs \ + --network host \ + -v /mnt/rustfs/data:/data \ + -e RUSTFS_ACCESS_KEY="" \ + -e RUSTFS_SECRET_KEY="" \ + -e RUSTFS_ADDRESS=":9000" \ + -e RUSTFS_CONSOLE_ADDRESS=":9001" \ + -e RUSTFS_CONSOLE_ENABLE=true \ + -e RUSTFS_OBS_LOGGER_LEVEL=error \ + -e RUSTFS_OBS_LOG_DIRECTORY="/var/log/rustfs/" \ + -e RUSTFS_VOLUMES="http://node{1...4}:9000/data/rustfs{0...3}" \ + rustfs/rustfs:latest +``` + +Add the entries to `/etc/hosts` on **every** node: + +```ini title="/etc/hosts" +192.168.1.1 node1 +192.168.1.2 node2 +192.168.1.3 node3 +192.168.1.4 node4 +``` + +## TLS configuration + +If [using TLS](../../integration/tls-configured.md), mount the certificate directory and point RustFS at it: + +```bash +-v /path/to/certs:/certs \ +-e RUSTFS_TLS_PATH=/certs \ +``` + +## Before production + +Work through the [Pre-Installation Checklists](../requirement/checklists/index.md) — hardware, network, software, and security — before deploying to production. Use a multi-node deployment architecture, [enable TLS encrypted communication](../../integration/tls-configured.md), configure a log rotation strategy, and set up a regular backup strategy. + ## Next steps - [RustFS Console](/administration/console) - [Configure an S3 client](../../developer/examples/aws-cli.md) -- [TLS configuration](../../integration/tls-configured.md) \ No newline at end of file +- [TLS configuration](../../integration/tls-configured.md) diff --git a/content/en/installation/container/index.md b/content/en/installation/container/index.md new file mode 100644 index 00000000..4ee47b47 --- /dev/null +++ b/content/en/installation/container/index.md @@ -0,0 +1,25 @@ +--- +title: "Container" +description: "Run the official RustFS container image with Docker or Podman." +--- + +RustFS is a high-performance, S3-compatible open-source distributed object storage system. In single-node single-disk (SNSD) deployment mode, the backend uses zero erasure coding without additional data redundancy, which makes it suitable for local testing and small-scale scenarios. The official RustFS image packages the RustFS binary and its runtime environment into a container, so you can start a service with a single command and persistent storage. + +The container runs as non-root user `rustfs` with id `10001`, so a bind-mounted host directory must be owned by `10001` to avoid permission denied errors. + +## Container runtimes + +- [Docker](./docker.md): run a single-node instance with persistent storage, then extend it with Docker Compose, TLS, and multi-node networking. +- [Podman](./podman.md): run the same image in a daemonless workflow. + +:::note[Directory permissions] + +If you mount a host directory into the container with `-v`, make sure the owner of the host directory is `10001`: + +```bash +chown -R 10001:10001 /path/to/host_directory +``` + +::: + +For Kubernetes deployments, see the [Helm chart](/installation/cloud-native/helm-chart) or the [Operator](/installation/cloud-native/operator) instead. diff --git a/content/en/installation/container/index.mdx b/content/en/installation/container/index.mdx deleted file mode 100644 index 27ed2b35..00000000 --- a/content/en/installation/container/index.mdx +++ /dev/null @@ -1,317 +0,0 @@ ---- -title: "Installing RustFS with Docker" -description: "RustFS Docker deployment." ---- - -RustFS is a high-performance, S3-compatible open-source distributed object storage system. In single-node single-disk (SNSD) deployment mode, the backend uses zero erasure coding without additional data redundancy, suitable for local testing and small-scale scenarios. -This article is based on RustFS official Linux binary packages, packaging RustFS and its runtime environment into containers through custom Dockerfile, and configuring data volumes and environment variables for one-click service startup. - ---- - -## 1. Prerequisites - -1. **Host Requirements** - - * Docker installed (≥ 20.10) and able to pull images and run containers normally - * Local path `/mnt/rustfs/data` (or custom path) for mounting object data - * [`rc`](/operations/rc) installed on the administration host for the verification workflow -2. **Network and Firewall** - - * Ensure host ports 9000 (S3 API) and 9001 (Console) are open to external access (or consistent with custom ports) - -3. **Directory Permissions** - - * The RustFS container runs as non-root user `rustfs` with id `10001`. If you run docker with `-v` to mount a host directory into the container, make sure the owner of the host directory is `10001`, otherwise you will encounter permission denied errors. Run `chown -R 10001:10001 /path/to/host_directory` to grant the necessary permissions. - ---- - -## 2. Pull the RustFS Official Image - -Pull the official image (Alpine-based) from Docker Hub: - -```bash -docker pull rustfs/rustfs -``` - ---- - - - -## 3. Run RustFS Container - -RustFS SNSD Docker running method, combining the above image and configuration, execute: - -```bash - docker run -d \ - --name rustfs_local \ - -p 9000:9000 \ - -p 9001:9001 \ - -v /mnt/rustfs/data:/data \ - rustfs/rustfs:latest \ - /data -``` - -Parameter descriptions: - -* `-p 9000:9000`: Map host port 9000 to container -* `-v /mnt/rustfs/data:/data`: Mount data volume -* `--name rustfs_local`: Custom container name -* `-d`: Run in background - ---- - -### Complete Configuration Example - -Configuration can be passed as environment variables (recommended) or as command-line flags — pick one style; when both are present, command-line flags win. The volume path (`/data`) always comes last. - - - - -```bash {7,8} -# Use a unique access key and a strong, random secret (e.g. openssl rand -base64 24) -docker run -d \ - --name rustfs \ - -p 9000:9000 \ - -p 9001:9001 \ - -v /mnt/rustfs/data:/data \ - -e RUSTFS_ACCESS_KEY="" \ - -e RUSTFS_SECRET_KEY="" \ - -e RUSTFS_ADDRESS=":9000" \ - -e RUSTFS_CONSOLE_ADDRESS=":9001" \ - -e RUSTFS_CONSOLE_ENABLE=true \ - -e RUSTFS_OBS_LOGGER_LEVEL=error \ - -e RUSTFS_OBS_LOG_DIRECTORY="/var/log/rustfs/" \ - rustfs/rustfs:latest \ - /data -``` - - - - -```bash {8,9} -# Use a unique access key and a strong, random secret (e.g. openssl rand -base64 24) -docker run -d \ - --name rustfs \ - -p 9000:9000 \ - -p 9001:9001 \ - -v /mnt/rustfs/data:/data \ - rustfs/rustfs:latest \ - --access-key "" \ - --secret-key "" \ - --address :9000 \ - --console-enable \ - /data -``` - - - - -### Common Configuration Combinations - -1. **Basic Configuration**: - ```bash - docker run -d \ - -p 9000:9000 \ - -p 9001:9001 \ - -v /mnt/data:/data \ - rustfs/rustfs:latest \ - /data - ``` - -2. **Enable Console**: - ```bash - docker run -d \ - -p 9000:9000 \ - -p 9001:9001 \ - -v /mnt/data:/data \ - -e RUSTFS_ADDRESS=":9000" \ - -e RUSTFS_CONSOLE_ADDRESS=":9001" \ - -e RUSTFS_CONSOLE_ENABLE=true \ - -e RUSTFS_OBS_LOGGER_LEVEL=error \ - -e RUSTFS_OBS_LOG_DIRECTORY="/var/log/rustfs/" \ - rustfs/rustfs:latest \ - --console-enable \ - /data - ``` - -3. **Custom Authentication Keys**: - ```bash - # Use a unique access key and a strong, random secret (e.g. openssl rand -base64 24) - docker run -d \ - -p 9000:9000 \ - -p 9001:9001 \ - -v /mnt/data:/data \ - -e RUSTFS_ACCESS_KEY="" \ - -e RUSTFS_SECRET_KEY="" \ - rustfs/rustfs:latest \ - --access-key "" \ - --secret-key "" \ - /data - ``` - -### Important Notes - -1. Port mapping must correspond: - - Service port defaults to 9000 (`-p 9000:9000`) - -2. Data volumes must be persistent: - - `-v /host/path:/container/path` - -3. Environment variables and command line parameters can be mixed, but command line parameters have higher priority - -4. If [using TLS](../../integration/tls-configured.md), additional certificate path mounting is needed: - - ```bash - -v /path/to/certs:/certs \ - -e RUSTFS_TLS_PATH=/certs \ - ``` - -### Docker Compose Installation - -RustFS officially provides a Docker Compose installation method. The [`docker-compose.yml`](https://github.com/rustfs/rustfs/blob/main/docker-compose.yml) file includes multiple services, such as `grafana`, `prometheus`, `otel-collector`, and `jaeger`, mainly for observability. If you want to deploy these services together, clone the [RustFS code repository](https://github.com/rustfs/rustfs) locally, - -```bash -git clone https://github.com/rustfs/rustfs.git -``` - -Running the command under root directory, - -```bash -docker compose --profile observability up -d -``` - -Providing the necessary permissions. An initialization container is necessary to grant the correct access rights to rustfs using the `depends_on` keyword. In the example below the `rustfs_perms` service is added to the `docker-compose.yml` to handle this. To ensure logs are persisted and accessible, we map the host log directory to the container's `/var/log/rustfs/` path - -```yaml title="docker-compose.yml" - services: - # grant the necessary permissions to RUSTFS volumes path - rustfs_perms: - image: alpine - user: root - volumes: - - /path/to/host_directory/volumes:/fix_path - command: chown -R 10001:10001 /fix_path - - rustfs: - image: rustfs/rustfs:latest - depends_on: - rustfs_perms: - condition: service_completed_successfully - volumes: - - /path/to_host_directory/volumes/data:/data - - /path/to_host_directory/volumes/logs:/var/log/rustfs/ - environment: - - RUSTFS_ADDRESS=":9000" - - RUSTFS_CONSOLE_ADDRESS=":9001" - - RUSTFS_CONSOLE_ENABLE=true - - RUSTFS_OBS_LOGGER_LEVEL=error - - RUSTFS_OBS_LOG_DIRECTORY="/var/log/rustfs/" - - # ... other configurations -``` - -Started containers is as below, - -```text -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -c13c23fe3d9d rustfs/rustfs:latest "/entrypoint.sh rust…" 6 seconds ago Up 5 seconds (health: starting) 0.0.0.0:9000-9001->9000-9001/tcp, :::9000-9001->9000-9001/tcp rustfs-server -e3f4fc4a83a2 grafana/grafana:latest "/run.sh" 7 seconds ago Up 5 seconds 0.0.0.0:3000->3000/tcp, :::3000->3000/tcp grafana -71ef1b8212cf prom/prometheus:latest "/bin/prometheus --c…" 7 seconds ago Up 5 seconds 0.0.0.0:9090->9090/tcp, :::9090->9090/tcp prometheus -e7db806b2d6f jaegertracing/all-in-one:latest "/go/bin/all-in-one-…" 7 seconds ago Up 5 seconds 4317-4318/tcp, 9411/tcp, 0.0.0.0:14250->14250/tcp, :::14250->14250/tcp, 14268/tcp, 0.0.0.0:16686->16686/tcp, :::16686->16686/tcp jaeger -1897830a2f1e otel/opentelemetry-collector-contrib:latest "/otelcol-contrib --…" 7 seconds ago Up 5 seconds 0.0.0.0:4317-4318->4317-4318/tcp, :::4317-4318->4317-4318/tcp, 0.0.0.0:8888-8889->8888-8889/tcp, :::8888-8889->8888-8889/tcp, 55679/tcp otel-collector -``` - -If you only want to install RustFS without Grafana, Prometheus, and the other observability services, start just the `rustfs` service (the compose file marks the collector dependency as optional): - -```bash -docker compose -f docker-compose.yml up -d rustfs -``` - -This way will only install and start `rustfs-server` service, namely rustfs container, - -```text -docker ps -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -e07121ecdd39 rustfs/rustfs:latest "/entrypoint.sh rust…" 2 seconds ago Up 1 second (health: starting) 0.0.0.0:9000-9001->9000-9001/tcp, :::9000-9001->9000-9001/tcp rustfs-server -``` - -Whether you start only the `rustfs-server` or together with observability services, the S3 API is served at `http://localhost:9000`, and the RustFS Console is at `http://localhost:9001` — open it in a browser and log in with the access key and secret key you configured above (the `` / `` placeholders). Generate a strong secret with, for example, `openssl rand -base64 24`, and never ship the placeholder values to production. - -:::warning[Set container credentials immediately] - -Set unique `RUSTFS_ACCESS_KEY` and `RUSTFS_SECRET_KEY` environment variables before exposing RustFS to a network. Do not use the well-known `rustfsadmin` value for either credential. For `docker run`, pass both values with `-e`. For Docker Compose, define both variables in the `rustfs` service environment or in the environment file used for variable substitution, then recreate the service with `docker compose up -d rustfs`. - -::: - -## 4. Verification and Access - -1. **View Container Status and Logs:** - - ```bash - docker logs rustfs_local - ``` - - Logs should show successful service startup and listening on port 9000. - -2. **Test S3 API:** - - Use `rc` to verify the S3 API: - - ```bash - # Use a unique access key and a strong, random secret (e.g. openssl rand -base64 24) - rc alias set rustfs http://localhost:9000 - rc bucket create rustfs/my-bucket - rc bucket list rustfs/ - ``` - - If buckets can be successfully created and listed, deployment is effective. - -## 5. Multiple Nodes - -Dockers default bridge networking does not support multi-node deployments. Use `--network host` so each container can communicate directly with other nodes. - -Run the following on **each node** - -```bash -# Use a unique access key and a strong, random secret (e.g. openssl rand -base64 24) -docker run -d \ - --name rustfs \ - --network host \ - -v /mnt/rustfs/data:/data \ - -e RUSTFS_ACCESS_KEY="" \ - -e RUSTFS_SECRET_KEY="" \ - -e RUSTFS_ADDRESS=":9000" \ - -e RUSTFS_CONSOLE_ADDRESS=":9001" \ - -e RUSTFS_CONSOLE_ENABLE=true \ - -e RUSTFS_OBS_LOGGER_LEVEL=error \ - -e RUSTFS_OBS_LOG_DIRECTORY="/var/log/rustfs/" \ - -e RUSTFS_VOLUMES="http://node{1...4}:9000/data/rustfs{0...3}" \ - rustfs/rustfs:latest -``` - -Add the entries to `/etc/hosts` on **every** node: -```ini title="/etc/hosts" -192.168.1.1 node1 -192.168.1.2 node2 -192.168.1.3 node3 -192.168.1.4 node4 -``` - -## 6. Other Recommendations - -1. Production Environment Recommendations: -- Use multi-node deployment architecture -- [Enable TLS encrypted communication](../../integration/tls-configured.md) -- Configure log rotation strategy -- Set up regular backup strategy - -2. Storage Recommendations: -- Use local SSD/NVMe storage -- Avoid using network file systems (NFS) -- Ensure storage directory exclusive access - ---- - -## Summary - -This article explains how to deploy RustFS using Docker with best practices, starting with a single-node single-disk (SNSD) setup and then extending to a multi-node deployment option. diff --git a/content/en/installation/container/podman.md b/content/en/installation/container/podman.md index 5c478328..9ce2a6fc 100644 --- a/content/en/installation/container/podman.md +++ b/content/en/installation/container/podman.md @@ -19,6 +19,16 @@ Create a named volume so object data remains available when you replace the cont podman volume create rustfs-data ``` +:::note[Bind-mounting a host directory] + +The named volume above needs no extra setup. If you bind-mount a host directory instead, keep in mind that the container runs as non-root user `rustfs` with id `10001`. Make the host directory owned by `10001`, otherwise you will encounter permission denied errors: + +```bash +chown -R 10001:10001 /path/to/host_directory +``` + +::: + ## 3. Start RustFS Replace the credential placeholders before running the container: @@ -61,4 +71,4 @@ The S3 API is available at `http://localhost:9000`, and the Console is available - [RustFS Console](/administration/console) - [Configure an S3 client](../../developer/examples/aws-cli.md) -- [TLS configuration](../../integration/tls-configured.md) \ No newline at end of file +- [TLS configuration](../../integration/tls-configured.md) diff --git a/content/en/installation/index.md b/content/en/installation/index.md index e7985e53..4d8361f5 100644 --- a/content/en/installation/index.md +++ b/content/en/installation/index.md @@ -18,7 +18,7 @@ After installation, set unique values for `RUSTFS_ACCESS_KEY` and `RUSTFS_SECRET | Your goal | Recommended path | Guide | | - | - | - | -| Try RustFS on a local machine | One-command install script, or a container | [Linux Quick Start](./linux/quick-start.md) · [Container](./container/index.mdx) | +| Try RustFS on a local machine | One-command install script, or a container | [Linux Quick Start](./linux/quick-start.md) · [Container](./container/index.md) | | Single-server production | SNSD (one disk) or SNMD (multiple disks) | [Installing RustFS on Linux](./linux/index.md) | | Multi-server production cluster | MNMD, after completing the production checklists | [Multiple Node Multiple Disk](./linux/multiple-node-multiple-disk.md) · [Checklists](./requirement/checklists/index.md) | | Kubernetes / cloud-native | Container orchestration deployment | [Cloud Native](./cloud-native/index.md) | diff --git a/content/en/installation/linux/quick-start.md b/content/en/installation/linux/quick-start.md index a43b7ef0..c72007b7 100644 --- a/content/en/installation/linux/quick-start.md +++ b/content/en/installation/linux/quick-start.md @@ -88,5 +88,5 @@ The quick install runs RustFS in **Single Node Single Disk (SNSD)** mode — zer - [Single Node Single Disk (SNSD)](./single-node-single-disk.md) — dev and small workloads - [Single Node Multiple Disk (SNMD)](./single-node-multiple-disk.md) — disk-level fault tolerance on one machine - [Multiple Node Multiple Disk (MNMD)](./multiple-node-multiple-disk.md) — production-grade availability and scale, with the [pre-installation checklists](../requirement/checklists/index.md) -- **Prefer containers?** — [Install with a container](../container/index.mdx) +- **Prefer containers?** — [Install with a container](../container/index.md) - **Connect your application** — [SDKs and examples](../../developer/sdk/index.md) diff --git a/content/fr/installation/container/docker.md b/content/fr/installation/container/docker.md index 8469df29..c88d6100 100644 --- a/content/fr/installation/container/docker.md +++ b/content/fr/installation/container/docker.md @@ -1,17 +1,23 @@ --- title: "Docker" -description: "Run a single-node RustFS instance with Docker and persistent container storage." +description: "Run RustFS with Docker: single-node setup, host-directory permissions, Docker Compose, TLS, and multi-node deployment." --- -Use the official RustFS image to start a single-node instance with persistent storage. You need a working Docker Engine and permission to run containers. +This page covers running the official RustFS image with Docker: a single-node instance with persistent storage, host-directory permissions for the non-root container user, Docker Compose with optional observability services, TLS, and a multi-node deployment. You need a working Docker Engine and permission to run containers. -## 1. Pull the image +## 1. Prerequisites + +* Docker Engine (≥ 20.10) installed and able to pull images and run containers normally +* Host ports 9000 (S3 API) and 9001 (Console) available, or consistent with your custom ports +* If you bind-mount a host directory, the directory owner must match the container user — see [Bind-mount a host directory](#bind-mount-a-host-directory) + +## 2. Pull the image ```bash docker pull rustfs/rustfs:latest ``` -## 2. Create persistent storage +## 3. Create persistent storage Create a named volume so object data remains available when you replace the container: @@ -19,7 +25,7 @@ Create a named volume so object data remains available when you replace the cont docker volume create rustfs-data ``` -## 3. Start RustFS +## 4. Start RustFS Replace the credential placeholders before running the container: @@ -47,7 +53,33 @@ Set unique `RUSTFS_ACCESS_KEY` and `RUSTFS_SECRET_KEY` environment variables bef ::: -## 4. Verify the deployment +### Environment variables or command-line flags + +The example above configures RustFS with environment variables. You can pass the same settings as command-line flags instead; when both are present, command-line flags win: + +```bash +docker run -d \ + --name rustfs \ + -p 9000:9000 \ + -p 9001:9001 \ + -v rustfs-data:/data \ + rustfs/rustfs:latest \ + --access-key "" \ + --secret-key "" \ + --address :9000 \ + --console-enable \ + /data +``` + +## 5. Bind-mount a host directory + +The named volume above needs no extra setup. If you mount a host directory instead (`-v /path/on/host:/data`), keep in mind that the container runs as non-root user `rustfs` with id `10001`. Make the host directory owned by `10001`, otherwise you will encounter permission denied errors: + +```bash +chown -R 10001:10001 /path/to/host_directory +``` + +## 6. Verify the deployment Check the container and the S3 API health endpoint: @@ -58,8 +90,106 @@ curl --fail http://localhost:9000/health The S3 API is available at `http://localhost:9000`, and the Console is available at `http://localhost:9001`. +## Docker Compose + +The RustFS repository ships a [`docker-compose.yml`](https://github.com/rustfs/rustfs/blob/main/docker-compose.yml) that includes `grafana`, `prometheus`, `otel-collector`, and `jaeger` services, mainly for observability. To deploy RustFS together with these services, clone the [RustFS code repository](https://github.com/rustfs/rustfs) locally: + +```bash +git clone https://github.com/rustfs/rustfs.git +``` + +Run the command from the repository root: + +```bash +docker compose --profile observability up -d +``` + +The compose file uses an initialization container to grant the correct access rights to `rustfs`: the `rustfs_perms` service below changes the ownership of the mounted volumes to `10001` before `rustfs` starts, using `depends_on` to wait for it to complete. To keep logs persistent and accessible, the host log directory is mapped to the container's `/var/log/rustfs/` path: + +```yaml title="docker-compose.yml" + services: + # grant the necessary permissions to RUSTFS volumes path + rustfs_perms: + image: alpine + user: root + volumes: + - /path/to/host_directory/volumes:/fix_path + command: chown -R 10001:10001 /fix_path + + rustfs: + image: rustfs/rustfs:latest + depends_on: + rustfs_perms: + condition: service_completed_successfully + volumes: + - /path/to_host_directory/volumes/data:/data + - /path/to_host_directory/volumes/logs:/var/log/rustfs/ + environment: + - RUSTFS_ADDRESS=":9000" + - RUSTFS_CONSOLE_ADDRESS=":9001" + - RUSTFS_CONSOLE_ENABLE=true + - RUSTFS_OBS_LOGGER_LEVEL=error + - RUSTFS_OBS_LOG_DIRECTORY="/var/log/rustfs/" + + # ... other configurations +``` + +If you only want RustFS without Grafana, Prometheus, and the other observability services, start just the `rustfs` service (the compose file marks the collector dependency as optional): + +```bash +docker compose -f docker-compose.yml up -d rustfs +``` + +This starts only the `rustfs-server` container. Whether you start only `rustfs-server` or the full stack, the S3 API is served at `http://localhost:9000`, and the RustFS Console is at `http://localhost:9001`. Open the Console in a browser and log in with the access key and secret key you configured above. Generate a strong secret with, for example, `openssl rand -base64 24`, and never ship the placeholder values to production. + +For Docker Compose, define unique `RUSTFS_ACCESS_KEY` and `RUSTFS_SECRET_KEY` values in the `rustfs` service environment or in the environment file used for variable substitution, then recreate the service with `docker compose up -d rustfs`. + +## Multi-node deployment + +Docker's default bridge networking does not support multi-node deployments. Use `--network host` so each container can communicate directly with other nodes. + +Run the following on **each node**: + +```bash +docker run -d \ + --name rustfs \ + --network host \ + -v /mnt/rustfs/data:/data \ + -e RUSTFS_ACCESS_KEY="" \ + -e RUSTFS_SECRET_KEY="" \ + -e RUSTFS_ADDRESS=":9000" \ + -e RUSTFS_CONSOLE_ADDRESS=":9001" \ + -e RUSTFS_CONSOLE_ENABLE=true \ + -e RUSTFS_OBS_LOGGER_LEVEL=error \ + -e RUSTFS_OBS_LOG_DIRECTORY="/var/log/rustfs/" \ + -e RUSTFS_VOLUMES="http://node{1...4}:9000/data/rustfs{0...3}" \ + rustfs/rustfs:latest +``` + +Add the entries to `/etc/hosts` on **every** node: + +```ini title="/etc/hosts" +192.168.1.1 node1 +192.168.1.2 node2 +192.168.1.3 node3 +192.168.1.4 node4 +``` + +## TLS configuration + +If [using TLS](../../integration/tls-configured.md), mount the certificate directory and point RustFS at it: + +```bash +-v /path/to/certs:/certs \ +-e RUSTFS_TLS_PATH=/certs \ +``` + +## Before production + +Work through the [Pre-Installation Checklists](../requirement/checklists/index.md) — hardware, network, software, and security — before deploying to production. Use a multi-node deployment architecture, [enable TLS encrypted communication](../../integration/tls-configured.md), configure a log rotation strategy, and set up a regular backup strategy. + ## Next steps - [RustFS Console](/administration/console) - [Configure an S3 client](../../developer/examples/aws-cli.md) -- [TLS configuration](../../integration/tls-configured.md) \ No newline at end of file +- [TLS configuration](../../integration/tls-configured.md) diff --git a/content/fr/installation/container/index.md b/content/fr/installation/container/index.md new file mode 100644 index 00000000..4ee47b47 --- /dev/null +++ b/content/fr/installation/container/index.md @@ -0,0 +1,25 @@ +--- +title: "Container" +description: "Run the official RustFS container image with Docker or Podman." +--- + +RustFS is a high-performance, S3-compatible open-source distributed object storage system. In single-node single-disk (SNSD) deployment mode, the backend uses zero erasure coding without additional data redundancy, which makes it suitable for local testing and small-scale scenarios. The official RustFS image packages the RustFS binary and its runtime environment into a container, so you can start a service with a single command and persistent storage. + +The container runs as non-root user `rustfs` with id `10001`, so a bind-mounted host directory must be owned by `10001` to avoid permission denied errors. + +## Container runtimes + +- [Docker](./docker.md): run a single-node instance with persistent storage, then extend it with Docker Compose, TLS, and multi-node networking. +- [Podman](./podman.md): run the same image in a daemonless workflow. + +:::note[Directory permissions] + +If you mount a host directory into the container with `-v`, make sure the owner of the host directory is `10001`: + +```bash +chown -R 10001:10001 /path/to/host_directory +``` + +::: + +For Kubernetes deployments, see the [Helm chart](/installation/cloud-native/helm-chart) or the [Operator](/installation/cloud-native/operator) instead. diff --git a/content/fr/installation/container/index.mdx b/content/fr/installation/container/index.mdx deleted file mode 100644 index 27ed2b35..00000000 --- a/content/fr/installation/container/index.mdx +++ /dev/null @@ -1,317 +0,0 @@ ---- -title: "Installing RustFS with Docker" -description: "RustFS Docker deployment." ---- - -RustFS is a high-performance, S3-compatible open-source distributed object storage system. In single-node single-disk (SNSD) deployment mode, the backend uses zero erasure coding without additional data redundancy, suitable for local testing and small-scale scenarios. -This article is based on RustFS official Linux binary packages, packaging RustFS and its runtime environment into containers through custom Dockerfile, and configuring data volumes and environment variables for one-click service startup. - ---- - -## 1. Prerequisites - -1. **Host Requirements** - - * Docker installed (≥ 20.10) and able to pull images and run containers normally - * Local path `/mnt/rustfs/data` (or custom path) for mounting object data - * [`rc`](/operations/rc) installed on the administration host for the verification workflow -2. **Network and Firewall** - - * Ensure host ports 9000 (S3 API) and 9001 (Console) are open to external access (or consistent with custom ports) - -3. **Directory Permissions** - - * The RustFS container runs as non-root user `rustfs` with id `10001`. If you run docker with `-v` to mount a host directory into the container, make sure the owner of the host directory is `10001`, otherwise you will encounter permission denied errors. Run `chown -R 10001:10001 /path/to/host_directory` to grant the necessary permissions. - ---- - -## 2. Pull the RustFS Official Image - -Pull the official image (Alpine-based) from Docker Hub: - -```bash -docker pull rustfs/rustfs -``` - ---- - - - -## 3. Run RustFS Container - -RustFS SNSD Docker running method, combining the above image and configuration, execute: - -```bash - docker run -d \ - --name rustfs_local \ - -p 9000:9000 \ - -p 9001:9001 \ - -v /mnt/rustfs/data:/data \ - rustfs/rustfs:latest \ - /data -``` - -Parameter descriptions: - -* `-p 9000:9000`: Map host port 9000 to container -* `-v /mnt/rustfs/data:/data`: Mount data volume -* `--name rustfs_local`: Custom container name -* `-d`: Run in background - ---- - -### Complete Configuration Example - -Configuration can be passed as environment variables (recommended) or as command-line flags — pick one style; when both are present, command-line flags win. The volume path (`/data`) always comes last. - - - - -```bash {7,8} -# Use a unique access key and a strong, random secret (e.g. openssl rand -base64 24) -docker run -d \ - --name rustfs \ - -p 9000:9000 \ - -p 9001:9001 \ - -v /mnt/rustfs/data:/data \ - -e RUSTFS_ACCESS_KEY="" \ - -e RUSTFS_SECRET_KEY="" \ - -e RUSTFS_ADDRESS=":9000" \ - -e RUSTFS_CONSOLE_ADDRESS=":9001" \ - -e RUSTFS_CONSOLE_ENABLE=true \ - -e RUSTFS_OBS_LOGGER_LEVEL=error \ - -e RUSTFS_OBS_LOG_DIRECTORY="/var/log/rustfs/" \ - rustfs/rustfs:latest \ - /data -``` - - - - -```bash {8,9} -# Use a unique access key and a strong, random secret (e.g. openssl rand -base64 24) -docker run -d \ - --name rustfs \ - -p 9000:9000 \ - -p 9001:9001 \ - -v /mnt/rustfs/data:/data \ - rustfs/rustfs:latest \ - --access-key "" \ - --secret-key "" \ - --address :9000 \ - --console-enable \ - /data -``` - - - - -### Common Configuration Combinations - -1. **Basic Configuration**: - ```bash - docker run -d \ - -p 9000:9000 \ - -p 9001:9001 \ - -v /mnt/data:/data \ - rustfs/rustfs:latest \ - /data - ``` - -2. **Enable Console**: - ```bash - docker run -d \ - -p 9000:9000 \ - -p 9001:9001 \ - -v /mnt/data:/data \ - -e RUSTFS_ADDRESS=":9000" \ - -e RUSTFS_CONSOLE_ADDRESS=":9001" \ - -e RUSTFS_CONSOLE_ENABLE=true \ - -e RUSTFS_OBS_LOGGER_LEVEL=error \ - -e RUSTFS_OBS_LOG_DIRECTORY="/var/log/rustfs/" \ - rustfs/rustfs:latest \ - --console-enable \ - /data - ``` - -3. **Custom Authentication Keys**: - ```bash - # Use a unique access key and a strong, random secret (e.g. openssl rand -base64 24) - docker run -d \ - -p 9000:9000 \ - -p 9001:9001 \ - -v /mnt/data:/data \ - -e RUSTFS_ACCESS_KEY="" \ - -e RUSTFS_SECRET_KEY="" \ - rustfs/rustfs:latest \ - --access-key "" \ - --secret-key "" \ - /data - ``` - -### Important Notes - -1. Port mapping must correspond: - - Service port defaults to 9000 (`-p 9000:9000`) - -2. Data volumes must be persistent: - - `-v /host/path:/container/path` - -3. Environment variables and command line parameters can be mixed, but command line parameters have higher priority - -4. If [using TLS](../../integration/tls-configured.md), additional certificate path mounting is needed: - - ```bash - -v /path/to/certs:/certs \ - -e RUSTFS_TLS_PATH=/certs \ - ``` - -### Docker Compose Installation - -RustFS officially provides a Docker Compose installation method. The [`docker-compose.yml`](https://github.com/rustfs/rustfs/blob/main/docker-compose.yml) file includes multiple services, such as `grafana`, `prometheus`, `otel-collector`, and `jaeger`, mainly for observability. If you want to deploy these services together, clone the [RustFS code repository](https://github.com/rustfs/rustfs) locally, - -```bash -git clone https://github.com/rustfs/rustfs.git -``` - -Running the command under root directory, - -```bash -docker compose --profile observability up -d -``` - -Providing the necessary permissions. An initialization container is necessary to grant the correct access rights to rustfs using the `depends_on` keyword. In the example below the `rustfs_perms` service is added to the `docker-compose.yml` to handle this. To ensure logs are persisted and accessible, we map the host log directory to the container's `/var/log/rustfs/` path - -```yaml title="docker-compose.yml" - services: - # grant the necessary permissions to RUSTFS volumes path - rustfs_perms: - image: alpine - user: root - volumes: - - /path/to/host_directory/volumes:/fix_path - command: chown -R 10001:10001 /fix_path - - rustfs: - image: rustfs/rustfs:latest - depends_on: - rustfs_perms: - condition: service_completed_successfully - volumes: - - /path/to_host_directory/volumes/data:/data - - /path/to_host_directory/volumes/logs:/var/log/rustfs/ - environment: - - RUSTFS_ADDRESS=":9000" - - RUSTFS_CONSOLE_ADDRESS=":9001" - - RUSTFS_CONSOLE_ENABLE=true - - RUSTFS_OBS_LOGGER_LEVEL=error - - RUSTFS_OBS_LOG_DIRECTORY="/var/log/rustfs/" - - # ... other configurations -``` - -Started containers is as below, - -```text -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -c13c23fe3d9d rustfs/rustfs:latest "/entrypoint.sh rust…" 6 seconds ago Up 5 seconds (health: starting) 0.0.0.0:9000-9001->9000-9001/tcp, :::9000-9001->9000-9001/tcp rustfs-server -e3f4fc4a83a2 grafana/grafana:latest "/run.sh" 7 seconds ago Up 5 seconds 0.0.0.0:3000->3000/tcp, :::3000->3000/tcp grafana -71ef1b8212cf prom/prometheus:latest "/bin/prometheus --c…" 7 seconds ago Up 5 seconds 0.0.0.0:9090->9090/tcp, :::9090->9090/tcp prometheus -e7db806b2d6f jaegertracing/all-in-one:latest "/go/bin/all-in-one-…" 7 seconds ago Up 5 seconds 4317-4318/tcp, 9411/tcp, 0.0.0.0:14250->14250/tcp, :::14250->14250/tcp, 14268/tcp, 0.0.0.0:16686->16686/tcp, :::16686->16686/tcp jaeger -1897830a2f1e otel/opentelemetry-collector-contrib:latest "/otelcol-contrib --…" 7 seconds ago Up 5 seconds 0.0.0.0:4317-4318->4317-4318/tcp, :::4317-4318->4317-4318/tcp, 0.0.0.0:8888-8889->8888-8889/tcp, :::8888-8889->8888-8889/tcp, 55679/tcp otel-collector -``` - -If you only want to install RustFS without Grafana, Prometheus, and the other observability services, start just the `rustfs` service (the compose file marks the collector dependency as optional): - -```bash -docker compose -f docker-compose.yml up -d rustfs -``` - -This way will only install and start `rustfs-server` service, namely rustfs container, - -```text -docker ps -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -e07121ecdd39 rustfs/rustfs:latest "/entrypoint.sh rust…" 2 seconds ago Up 1 second (health: starting) 0.0.0.0:9000-9001->9000-9001/tcp, :::9000-9001->9000-9001/tcp rustfs-server -``` - -Whether you start only the `rustfs-server` or together with observability services, the S3 API is served at `http://localhost:9000`, and the RustFS Console is at `http://localhost:9001` — open it in a browser and log in with the access key and secret key you configured above (the `` / `` placeholders). Generate a strong secret with, for example, `openssl rand -base64 24`, and never ship the placeholder values to production. - -:::warning[Set container credentials immediately] - -Set unique `RUSTFS_ACCESS_KEY` and `RUSTFS_SECRET_KEY` environment variables before exposing RustFS to a network. Do not use the well-known `rustfsadmin` value for either credential. For `docker run`, pass both values with `-e`. For Docker Compose, define both variables in the `rustfs` service environment or in the environment file used for variable substitution, then recreate the service with `docker compose up -d rustfs`. - -::: - -## 4. Verification and Access - -1. **View Container Status and Logs:** - - ```bash - docker logs rustfs_local - ``` - - Logs should show successful service startup and listening on port 9000. - -2. **Test S3 API:** - - Use `rc` to verify the S3 API: - - ```bash - # Use a unique access key and a strong, random secret (e.g. openssl rand -base64 24) - rc alias set rustfs http://localhost:9000 - rc bucket create rustfs/my-bucket - rc bucket list rustfs/ - ``` - - If buckets can be successfully created and listed, deployment is effective. - -## 5. Multiple Nodes - -Dockers default bridge networking does not support multi-node deployments. Use `--network host` so each container can communicate directly with other nodes. - -Run the following on **each node** - -```bash -# Use a unique access key and a strong, random secret (e.g. openssl rand -base64 24) -docker run -d \ - --name rustfs \ - --network host \ - -v /mnt/rustfs/data:/data \ - -e RUSTFS_ACCESS_KEY="" \ - -e RUSTFS_SECRET_KEY="" \ - -e RUSTFS_ADDRESS=":9000" \ - -e RUSTFS_CONSOLE_ADDRESS=":9001" \ - -e RUSTFS_CONSOLE_ENABLE=true \ - -e RUSTFS_OBS_LOGGER_LEVEL=error \ - -e RUSTFS_OBS_LOG_DIRECTORY="/var/log/rustfs/" \ - -e RUSTFS_VOLUMES="http://node{1...4}:9000/data/rustfs{0...3}" \ - rustfs/rustfs:latest -``` - -Add the entries to `/etc/hosts` on **every** node: -```ini title="/etc/hosts" -192.168.1.1 node1 -192.168.1.2 node2 -192.168.1.3 node3 -192.168.1.4 node4 -``` - -## 6. Other Recommendations - -1. Production Environment Recommendations: -- Use multi-node deployment architecture -- [Enable TLS encrypted communication](../../integration/tls-configured.md) -- Configure log rotation strategy -- Set up regular backup strategy - -2. Storage Recommendations: -- Use local SSD/NVMe storage -- Avoid using network file systems (NFS) -- Ensure storage directory exclusive access - ---- - -## Summary - -This article explains how to deploy RustFS using Docker with best practices, starting with a single-node single-disk (SNSD) setup and then extending to a multi-node deployment option. diff --git a/content/fr/installation/container/podman.md b/content/fr/installation/container/podman.md index 5c478328..9ce2a6fc 100644 --- a/content/fr/installation/container/podman.md +++ b/content/fr/installation/container/podman.md @@ -19,6 +19,16 @@ Create a named volume so object data remains available when you replace the cont podman volume create rustfs-data ``` +:::note[Bind-mounting a host directory] + +The named volume above needs no extra setup. If you bind-mount a host directory instead, keep in mind that the container runs as non-root user `rustfs` with id `10001`. Make the host directory owned by `10001`, otherwise you will encounter permission denied errors: + +```bash +chown -R 10001:10001 /path/to/host_directory +``` + +::: + ## 3. Start RustFS Replace the credential placeholders before running the container: @@ -61,4 +71,4 @@ The S3 API is available at `http://localhost:9000`, and the Console is available - [RustFS Console](/administration/console) - [Configure an S3 client](../../developer/examples/aws-cli.md) -- [TLS configuration](../../integration/tls-configured.md) \ No newline at end of file +- [TLS configuration](../../integration/tls-configured.md) diff --git a/content/fr/installation/index.md b/content/fr/installation/index.md index e7985e53..4d8361f5 100644 --- a/content/fr/installation/index.md +++ b/content/fr/installation/index.md @@ -18,7 +18,7 @@ After installation, set unique values for `RUSTFS_ACCESS_KEY` and `RUSTFS_SECRET | Your goal | Recommended path | Guide | | - | - | - | -| Try RustFS on a local machine | One-command install script, or a container | [Linux Quick Start](./linux/quick-start.md) · [Container](./container/index.mdx) | +| Try RustFS on a local machine | One-command install script, or a container | [Linux Quick Start](./linux/quick-start.md) · [Container](./container/index.md) | | Single-server production | SNSD (one disk) or SNMD (multiple disks) | [Installing RustFS on Linux](./linux/index.md) | | Multi-server production cluster | MNMD, after completing the production checklists | [Multiple Node Multiple Disk](./linux/multiple-node-multiple-disk.md) · [Checklists](./requirement/checklists/index.md) | | Kubernetes / cloud-native | Container orchestration deployment | [Cloud Native](./cloud-native/index.md) | diff --git a/content/fr/installation/linux/quick-start.md b/content/fr/installation/linux/quick-start.md index a43b7ef0..c72007b7 100644 --- a/content/fr/installation/linux/quick-start.md +++ b/content/fr/installation/linux/quick-start.md @@ -88,5 +88,5 @@ The quick install runs RustFS in **Single Node Single Disk (SNSD)** mode — zer - [Single Node Single Disk (SNSD)](./single-node-single-disk.md) — dev and small workloads - [Single Node Multiple Disk (SNMD)](./single-node-multiple-disk.md) — disk-level fault tolerance on one machine - [Multiple Node Multiple Disk (MNMD)](./multiple-node-multiple-disk.md) — production-grade availability and scale, with the [pre-installation checklists](../requirement/checklists/index.md) -- **Prefer containers?** — [Install with a container](../container/index.mdx) +- **Prefer containers?** — [Install with a container](../container/index.md) - **Connect your application** — [SDKs and examples](../../developer/sdk/index.md) diff --git a/content/ja/installation/container/docker.md b/content/ja/installation/container/docker.md index 8469df29..c88d6100 100644 --- a/content/ja/installation/container/docker.md +++ b/content/ja/installation/container/docker.md @@ -1,17 +1,23 @@ --- title: "Docker" -description: "Run a single-node RustFS instance with Docker and persistent container storage." +description: "Run RustFS with Docker: single-node setup, host-directory permissions, Docker Compose, TLS, and multi-node deployment." --- -Use the official RustFS image to start a single-node instance with persistent storage. You need a working Docker Engine and permission to run containers. +This page covers running the official RustFS image with Docker: a single-node instance with persistent storage, host-directory permissions for the non-root container user, Docker Compose with optional observability services, TLS, and a multi-node deployment. You need a working Docker Engine and permission to run containers. -## 1. Pull the image +## 1. Prerequisites + +* Docker Engine (≥ 20.10) installed and able to pull images and run containers normally +* Host ports 9000 (S3 API) and 9001 (Console) available, or consistent with your custom ports +* If you bind-mount a host directory, the directory owner must match the container user — see [Bind-mount a host directory](#bind-mount-a-host-directory) + +## 2. Pull the image ```bash docker pull rustfs/rustfs:latest ``` -## 2. Create persistent storage +## 3. Create persistent storage Create a named volume so object data remains available when you replace the container: @@ -19,7 +25,7 @@ Create a named volume so object data remains available when you replace the cont docker volume create rustfs-data ``` -## 3. Start RustFS +## 4. Start RustFS Replace the credential placeholders before running the container: @@ -47,7 +53,33 @@ Set unique `RUSTFS_ACCESS_KEY` and `RUSTFS_SECRET_KEY` environment variables bef ::: -## 4. Verify the deployment +### Environment variables or command-line flags + +The example above configures RustFS with environment variables. You can pass the same settings as command-line flags instead; when both are present, command-line flags win: + +```bash +docker run -d \ + --name rustfs \ + -p 9000:9000 \ + -p 9001:9001 \ + -v rustfs-data:/data \ + rustfs/rustfs:latest \ + --access-key "" \ + --secret-key "" \ + --address :9000 \ + --console-enable \ + /data +``` + +## 5. Bind-mount a host directory + +The named volume above needs no extra setup. If you mount a host directory instead (`-v /path/on/host:/data`), keep in mind that the container runs as non-root user `rustfs` with id `10001`. Make the host directory owned by `10001`, otherwise you will encounter permission denied errors: + +```bash +chown -R 10001:10001 /path/to/host_directory +``` + +## 6. Verify the deployment Check the container and the S3 API health endpoint: @@ -58,8 +90,106 @@ curl --fail http://localhost:9000/health The S3 API is available at `http://localhost:9000`, and the Console is available at `http://localhost:9001`. +## Docker Compose + +The RustFS repository ships a [`docker-compose.yml`](https://github.com/rustfs/rustfs/blob/main/docker-compose.yml) that includes `grafana`, `prometheus`, `otel-collector`, and `jaeger` services, mainly for observability. To deploy RustFS together with these services, clone the [RustFS code repository](https://github.com/rustfs/rustfs) locally: + +```bash +git clone https://github.com/rustfs/rustfs.git +``` + +Run the command from the repository root: + +```bash +docker compose --profile observability up -d +``` + +The compose file uses an initialization container to grant the correct access rights to `rustfs`: the `rustfs_perms` service below changes the ownership of the mounted volumes to `10001` before `rustfs` starts, using `depends_on` to wait for it to complete. To keep logs persistent and accessible, the host log directory is mapped to the container's `/var/log/rustfs/` path: + +```yaml title="docker-compose.yml" + services: + # grant the necessary permissions to RUSTFS volumes path + rustfs_perms: + image: alpine + user: root + volumes: + - /path/to/host_directory/volumes:/fix_path + command: chown -R 10001:10001 /fix_path + + rustfs: + image: rustfs/rustfs:latest + depends_on: + rustfs_perms: + condition: service_completed_successfully + volumes: + - /path/to_host_directory/volumes/data:/data + - /path/to_host_directory/volumes/logs:/var/log/rustfs/ + environment: + - RUSTFS_ADDRESS=":9000" + - RUSTFS_CONSOLE_ADDRESS=":9001" + - RUSTFS_CONSOLE_ENABLE=true + - RUSTFS_OBS_LOGGER_LEVEL=error + - RUSTFS_OBS_LOG_DIRECTORY="/var/log/rustfs/" + + # ... other configurations +``` + +If you only want RustFS without Grafana, Prometheus, and the other observability services, start just the `rustfs` service (the compose file marks the collector dependency as optional): + +```bash +docker compose -f docker-compose.yml up -d rustfs +``` + +This starts only the `rustfs-server` container. Whether you start only `rustfs-server` or the full stack, the S3 API is served at `http://localhost:9000`, and the RustFS Console is at `http://localhost:9001`. Open the Console in a browser and log in with the access key and secret key you configured above. Generate a strong secret with, for example, `openssl rand -base64 24`, and never ship the placeholder values to production. + +For Docker Compose, define unique `RUSTFS_ACCESS_KEY` and `RUSTFS_SECRET_KEY` values in the `rustfs` service environment or in the environment file used for variable substitution, then recreate the service with `docker compose up -d rustfs`. + +## Multi-node deployment + +Docker's default bridge networking does not support multi-node deployments. Use `--network host` so each container can communicate directly with other nodes. + +Run the following on **each node**: + +```bash +docker run -d \ + --name rustfs \ + --network host \ + -v /mnt/rustfs/data:/data \ + -e RUSTFS_ACCESS_KEY="" \ + -e RUSTFS_SECRET_KEY="" \ + -e RUSTFS_ADDRESS=":9000" \ + -e RUSTFS_CONSOLE_ADDRESS=":9001" \ + -e RUSTFS_CONSOLE_ENABLE=true \ + -e RUSTFS_OBS_LOGGER_LEVEL=error \ + -e RUSTFS_OBS_LOG_DIRECTORY="/var/log/rustfs/" \ + -e RUSTFS_VOLUMES="http://node{1...4}:9000/data/rustfs{0...3}" \ + rustfs/rustfs:latest +``` + +Add the entries to `/etc/hosts` on **every** node: + +```ini title="/etc/hosts" +192.168.1.1 node1 +192.168.1.2 node2 +192.168.1.3 node3 +192.168.1.4 node4 +``` + +## TLS configuration + +If [using TLS](../../integration/tls-configured.md), mount the certificate directory and point RustFS at it: + +```bash +-v /path/to/certs:/certs \ +-e RUSTFS_TLS_PATH=/certs \ +``` + +## Before production + +Work through the [Pre-Installation Checklists](../requirement/checklists/index.md) — hardware, network, software, and security — before deploying to production. Use a multi-node deployment architecture, [enable TLS encrypted communication](../../integration/tls-configured.md), configure a log rotation strategy, and set up a regular backup strategy. + ## Next steps - [RustFS Console](/administration/console) - [Configure an S3 client](../../developer/examples/aws-cli.md) -- [TLS configuration](../../integration/tls-configured.md) \ No newline at end of file +- [TLS configuration](../../integration/tls-configured.md) diff --git a/content/ja/installation/container/index.md b/content/ja/installation/container/index.md new file mode 100644 index 00000000..4ee47b47 --- /dev/null +++ b/content/ja/installation/container/index.md @@ -0,0 +1,25 @@ +--- +title: "Container" +description: "Run the official RustFS container image with Docker or Podman." +--- + +RustFS is a high-performance, S3-compatible open-source distributed object storage system. In single-node single-disk (SNSD) deployment mode, the backend uses zero erasure coding without additional data redundancy, which makes it suitable for local testing and small-scale scenarios. The official RustFS image packages the RustFS binary and its runtime environment into a container, so you can start a service with a single command and persistent storage. + +The container runs as non-root user `rustfs` with id `10001`, so a bind-mounted host directory must be owned by `10001` to avoid permission denied errors. + +## Container runtimes + +- [Docker](./docker.md): run a single-node instance with persistent storage, then extend it with Docker Compose, TLS, and multi-node networking. +- [Podman](./podman.md): run the same image in a daemonless workflow. + +:::note[Directory permissions] + +If you mount a host directory into the container with `-v`, make sure the owner of the host directory is `10001`: + +```bash +chown -R 10001:10001 /path/to/host_directory +``` + +::: + +For Kubernetes deployments, see the [Helm chart](/installation/cloud-native/helm-chart) or the [Operator](/installation/cloud-native/operator) instead. diff --git a/content/ja/installation/container/index.mdx b/content/ja/installation/container/index.mdx deleted file mode 100644 index 27ed2b35..00000000 --- a/content/ja/installation/container/index.mdx +++ /dev/null @@ -1,317 +0,0 @@ ---- -title: "Installing RustFS with Docker" -description: "RustFS Docker deployment." ---- - -RustFS is a high-performance, S3-compatible open-source distributed object storage system. In single-node single-disk (SNSD) deployment mode, the backend uses zero erasure coding without additional data redundancy, suitable for local testing and small-scale scenarios. -This article is based on RustFS official Linux binary packages, packaging RustFS and its runtime environment into containers through custom Dockerfile, and configuring data volumes and environment variables for one-click service startup. - ---- - -## 1. Prerequisites - -1. **Host Requirements** - - * Docker installed (≥ 20.10) and able to pull images and run containers normally - * Local path `/mnt/rustfs/data` (or custom path) for mounting object data - * [`rc`](/operations/rc) installed on the administration host for the verification workflow -2. **Network and Firewall** - - * Ensure host ports 9000 (S3 API) and 9001 (Console) are open to external access (or consistent with custom ports) - -3. **Directory Permissions** - - * The RustFS container runs as non-root user `rustfs` with id `10001`. If you run docker with `-v` to mount a host directory into the container, make sure the owner of the host directory is `10001`, otherwise you will encounter permission denied errors. Run `chown -R 10001:10001 /path/to/host_directory` to grant the necessary permissions. - ---- - -## 2. Pull the RustFS Official Image - -Pull the official image (Alpine-based) from Docker Hub: - -```bash -docker pull rustfs/rustfs -``` - ---- - - - -## 3. Run RustFS Container - -RustFS SNSD Docker running method, combining the above image and configuration, execute: - -```bash - docker run -d \ - --name rustfs_local \ - -p 9000:9000 \ - -p 9001:9001 \ - -v /mnt/rustfs/data:/data \ - rustfs/rustfs:latest \ - /data -``` - -Parameter descriptions: - -* `-p 9000:9000`: Map host port 9000 to container -* `-v /mnt/rustfs/data:/data`: Mount data volume -* `--name rustfs_local`: Custom container name -* `-d`: Run in background - ---- - -### Complete Configuration Example - -Configuration can be passed as environment variables (recommended) or as command-line flags — pick one style; when both are present, command-line flags win. The volume path (`/data`) always comes last. - - - - -```bash {7,8} -# Use a unique access key and a strong, random secret (e.g. openssl rand -base64 24) -docker run -d \ - --name rustfs \ - -p 9000:9000 \ - -p 9001:9001 \ - -v /mnt/rustfs/data:/data \ - -e RUSTFS_ACCESS_KEY="" \ - -e RUSTFS_SECRET_KEY="" \ - -e RUSTFS_ADDRESS=":9000" \ - -e RUSTFS_CONSOLE_ADDRESS=":9001" \ - -e RUSTFS_CONSOLE_ENABLE=true \ - -e RUSTFS_OBS_LOGGER_LEVEL=error \ - -e RUSTFS_OBS_LOG_DIRECTORY="/var/log/rustfs/" \ - rustfs/rustfs:latest \ - /data -``` - - - - -```bash {8,9} -# Use a unique access key and a strong, random secret (e.g. openssl rand -base64 24) -docker run -d \ - --name rustfs \ - -p 9000:9000 \ - -p 9001:9001 \ - -v /mnt/rustfs/data:/data \ - rustfs/rustfs:latest \ - --access-key "" \ - --secret-key "" \ - --address :9000 \ - --console-enable \ - /data -``` - - - - -### Common Configuration Combinations - -1. **Basic Configuration**: - ```bash - docker run -d \ - -p 9000:9000 \ - -p 9001:9001 \ - -v /mnt/data:/data \ - rustfs/rustfs:latest \ - /data - ``` - -2. **Enable Console**: - ```bash - docker run -d \ - -p 9000:9000 \ - -p 9001:9001 \ - -v /mnt/data:/data \ - -e RUSTFS_ADDRESS=":9000" \ - -e RUSTFS_CONSOLE_ADDRESS=":9001" \ - -e RUSTFS_CONSOLE_ENABLE=true \ - -e RUSTFS_OBS_LOGGER_LEVEL=error \ - -e RUSTFS_OBS_LOG_DIRECTORY="/var/log/rustfs/" \ - rustfs/rustfs:latest \ - --console-enable \ - /data - ``` - -3. **Custom Authentication Keys**: - ```bash - # Use a unique access key and a strong, random secret (e.g. openssl rand -base64 24) - docker run -d \ - -p 9000:9000 \ - -p 9001:9001 \ - -v /mnt/data:/data \ - -e RUSTFS_ACCESS_KEY="" \ - -e RUSTFS_SECRET_KEY="" \ - rustfs/rustfs:latest \ - --access-key "" \ - --secret-key "" \ - /data - ``` - -### Important Notes - -1. Port mapping must correspond: - - Service port defaults to 9000 (`-p 9000:9000`) - -2. Data volumes must be persistent: - - `-v /host/path:/container/path` - -3. Environment variables and command line parameters can be mixed, but command line parameters have higher priority - -4. If [using TLS](../../integration/tls-configured.md), additional certificate path mounting is needed: - - ```bash - -v /path/to/certs:/certs \ - -e RUSTFS_TLS_PATH=/certs \ - ``` - -### Docker Compose Installation - -RustFS officially provides a Docker Compose installation method. The [`docker-compose.yml`](https://github.com/rustfs/rustfs/blob/main/docker-compose.yml) file includes multiple services, such as `grafana`, `prometheus`, `otel-collector`, and `jaeger`, mainly for observability. If you want to deploy these services together, clone the [RustFS code repository](https://github.com/rustfs/rustfs) locally, - -```bash -git clone https://github.com/rustfs/rustfs.git -``` - -Running the command under root directory, - -```bash -docker compose --profile observability up -d -``` - -Providing the necessary permissions. An initialization container is necessary to grant the correct access rights to rustfs using the `depends_on` keyword. In the example below the `rustfs_perms` service is added to the `docker-compose.yml` to handle this. To ensure logs are persisted and accessible, we map the host log directory to the container's `/var/log/rustfs/` path - -```yaml title="docker-compose.yml" - services: - # grant the necessary permissions to RUSTFS volumes path - rustfs_perms: - image: alpine - user: root - volumes: - - /path/to/host_directory/volumes:/fix_path - command: chown -R 10001:10001 /fix_path - - rustfs: - image: rustfs/rustfs:latest - depends_on: - rustfs_perms: - condition: service_completed_successfully - volumes: - - /path/to_host_directory/volumes/data:/data - - /path/to_host_directory/volumes/logs:/var/log/rustfs/ - environment: - - RUSTFS_ADDRESS=":9000" - - RUSTFS_CONSOLE_ADDRESS=":9001" - - RUSTFS_CONSOLE_ENABLE=true - - RUSTFS_OBS_LOGGER_LEVEL=error - - RUSTFS_OBS_LOG_DIRECTORY="/var/log/rustfs/" - - # ... other configurations -``` - -Started containers is as below, - -```text -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -c13c23fe3d9d rustfs/rustfs:latest "/entrypoint.sh rust…" 6 seconds ago Up 5 seconds (health: starting) 0.0.0.0:9000-9001->9000-9001/tcp, :::9000-9001->9000-9001/tcp rustfs-server -e3f4fc4a83a2 grafana/grafana:latest "/run.sh" 7 seconds ago Up 5 seconds 0.0.0.0:3000->3000/tcp, :::3000->3000/tcp grafana -71ef1b8212cf prom/prometheus:latest "/bin/prometheus --c…" 7 seconds ago Up 5 seconds 0.0.0.0:9090->9090/tcp, :::9090->9090/tcp prometheus -e7db806b2d6f jaegertracing/all-in-one:latest "/go/bin/all-in-one-…" 7 seconds ago Up 5 seconds 4317-4318/tcp, 9411/tcp, 0.0.0.0:14250->14250/tcp, :::14250->14250/tcp, 14268/tcp, 0.0.0.0:16686->16686/tcp, :::16686->16686/tcp jaeger -1897830a2f1e otel/opentelemetry-collector-contrib:latest "/otelcol-contrib --…" 7 seconds ago Up 5 seconds 0.0.0.0:4317-4318->4317-4318/tcp, :::4317-4318->4317-4318/tcp, 0.0.0.0:8888-8889->8888-8889/tcp, :::8888-8889->8888-8889/tcp, 55679/tcp otel-collector -``` - -If you only want to install RustFS without Grafana, Prometheus, and the other observability services, start just the `rustfs` service (the compose file marks the collector dependency as optional): - -```bash -docker compose -f docker-compose.yml up -d rustfs -``` - -This way will only install and start `rustfs-server` service, namely rustfs container, - -```text -docker ps -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -e07121ecdd39 rustfs/rustfs:latest "/entrypoint.sh rust…" 2 seconds ago Up 1 second (health: starting) 0.0.0.0:9000-9001->9000-9001/tcp, :::9000-9001->9000-9001/tcp rustfs-server -``` - -Whether you start only the `rustfs-server` or together with observability services, the S3 API is served at `http://localhost:9000`, and the RustFS Console is at `http://localhost:9001` — open it in a browser and log in with the access key and secret key you configured above (the `` / `` placeholders). Generate a strong secret with, for example, `openssl rand -base64 24`, and never ship the placeholder values to production. - -:::warning[Set container credentials immediately] - -Set unique `RUSTFS_ACCESS_KEY` and `RUSTFS_SECRET_KEY` environment variables before exposing RustFS to a network. Do not use the well-known `rustfsadmin` value for either credential. For `docker run`, pass both values with `-e`. For Docker Compose, define both variables in the `rustfs` service environment or in the environment file used for variable substitution, then recreate the service with `docker compose up -d rustfs`. - -::: - -## 4. Verification and Access - -1. **View Container Status and Logs:** - - ```bash - docker logs rustfs_local - ``` - - Logs should show successful service startup and listening on port 9000. - -2. **Test S3 API:** - - Use `rc` to verify the S3 API: - - ```bash - # Use a unique access key and a strong, random secret (e.g. openssl rand -base64 24) - rc alias set rustfs http://localhost:9000 - rc bucket create rustfs/my-bucket - rc bucket list rustfs/ - ``` - - If buckets can be successfully created and listed, deployment is effective. - -## 5. Multiple Nodes - -Dockers default bridge networking does not support multi-node deployments. Use `--network host` so each container can communicate directly with other nodes. - -Run the following on **each node** - -```bash -# Use a unique access key and a strong, random secret (e.g. openssl rand -base64 24) -docker run -d \ - --name rustfs \ - --network host \ - -v /mnt/rustfs/data:/data \ - -e RUSTFS_ACCESS_KEY="" \ - -e RUSTFS_SECRET_KEY="" \ - -e RUSTFS_ADDRESS=":9000" \ - -e RUSTFS_CONSOLE_ADDRESS=":9001" \ - -e RUSTFS_CONSOLE_ENABLE=true \ - -e RUSTFS_OBS_LOGGER_LEVEL=error \ - -e RUSTFS_OBS_LOG_DIRECTORY="/var/log/rustfs/" \ - -e RUSTFS_VOLUMES="http://node{1...4}:9000/data/rustfs{0...3}" \ - rustfs/rustfs:latest -``` - -Add the entries to `/etc/hosts` on **every** node: -```ini title="/etc/hosts" -192.168.1.1 node1 -192.168.1.2 node2 -192.168.1.3 node3 -192.168.1.4 node4 -``` - -## 6. Other Recommendations - -1. Production Environment Recommendations: -- Use multi-node deployment architecture -- [Enable TLS encrypted communication](../../integration/tls-configured.md) -- Configure log rotation strategy -- Set up regular backup strategy - -2. Storage Recommendations: -- Use local SSD/NVMe storage -- Avoid using network file systems (NFS) -- Ensure storage directory exclusive access - ---- - -## Summary - -This article explains how to deploy RustFS using Docker with best practices, starting with a single-node single-disk (SNSD) setup and then extending to a multi-node deployment option. diff --git a/content/ja/installation/container/podman.md b/content/ja/installation/container/podman.md index 5c478328..9ce2a6fc 100644 --- a/content/ja/installation/container/podman.md +++ b/content/ja/installation/container/podman.md @@ -19,6 +19,16 @@ Create a named volume so object data remains available when you replace the cont podman volume create rustfs-data ``` +:::note[Bind-mounting a host directory] + +The named volume above needs no extra setup. If you bind-mount a host directory instead, keep in mind that the container runs as non-root user `rustfs` with id `10001`. Make the host directory owned by `10001`, otherwise you will encounter permission denied errors: + +```bash +chown -R 10001:10001 /path/to/host_directory +``` + +::: + ## 3. Start RustFS Replace the credential placeholders before running the container: @@ -61,4 +71,4 @@ The S3 API is available at `http://localhost:9000`, and the Console is available - [RustFS Console](/administration/console) - [Configure an S3 client](../../developer/examples/aws-cli.md) -- [TLS configuration](../../integration/tls-configured.md) \ No newline at end of file +- [TLS configuration](../../integration/tls-configured.md) diff --git a/content/ja/installation/index.md b/content/ja/installation/index.md index e7985e53..4d8361f5 100644 --- a/content/ja/installation/index.md +++ b/content/ja/installation/index.md @@ -18,7 +18,7 @@ After installation, set unique values for `RUSTFS_ACCESS_KEY` and `RUSTFS_SECRET | Your goal | Recommended path | Guide | | - | - | - | -| Try RustFS on a local machine | One-command install script, or a container | [Linux Quick Start](./linux/quick-start.md) · [Container](./container/index.mdx) | +| Try RustFS on a local machine | One-command install script, or a container | [Linux Quick Start](./linux/quick-start.md) · [Container](./container/index.md) | | Single-server production | SNSD (one disk) or SNMD (multiple disks) | [Installing RustFS on Linux](./linux/index.md) | | Multi-server production cluster | MNMD, after completing the production checklists | [Multiple Node Multiple Disk](./linux/multiple-node-multiple-disk.md) · [Checklists](./requirement/checklists/index.md) | | Kubernetes / cloud-native | Container orchestration deployment | [Cloud Native](./cloud-native/index.md) | diff --git a/content/ja/installation/linux/quick-start.md b/content/ja/installation/linux/quick-start.md index a43b7ef0..c72007b7 100644 --- a/content/ja/installation/linux/quick-start.md +++ b/content/ja/installation/linux/quick-start.md @@ -88,5 +88,5 @@ The quick install runs RustFS in **Single Node Single Disk (SNSD)** mode — zer - [Single Node Single Disk (SNSD)](./single-node-single-disk.md) — dev and small workloads - [Single Node Multiple Disk (SNMD)](./single-node-multiple-disk.md) — disk-level fault tolerance on one machine - [Multiple Node Multiple Disk (MNMD)](./multiple-node-multiple-disk.md) — production-grade availability and scale, with the [pre-installation checklists](../requirement/checklists/index.md) -- **Prefer containers?** — [Install with a container](../container/index.mdx) +- **Prefer containers?** — [Install with a container](../container/index.md) - **Connect your application** — [SDKs and examples](../../developer/sdk/index.md) diff --git a/content/zh/installation/container/docker.md b/content/zh/installation/container/docker.md index 63fd2915..e35b3426 100644 --- a/content/zh/installation/container/docker.md +++ b/content/zh/installation/container/docker.md @@ -1,17 +1,23 @@ --- title: "Docker" -description: "使用 Docker 和持久化容器存储运行单节点 RustFS 实例。" +description: "使用 Docker 运行 RustFS：单节点部署、主机目录权限、Docker Compose、TLS 和多节点部署。" --- -使用官方 RustFS 镜像启动具有持久化存储的单节点实例。你需要可用的 Docker Engine，并拥有运行容器的权限。 +本页介绍如何使用官方 RustFS 镜像在 Docker 中运行 RustFS：带持久化存储的单节点实例、非 root 容器用户的主机目录权限、带可选可观测性服务的 Docker Compose、TLS 以及多节点部署。你需要可用的 Docker Engine，并拥有运行容器的权限。 -## 1. 拉取镜像 +## 1. 前提条件 + +* 已安装 Docker Engine（≥ 20.10），并能正常拉取镜像和运行容器 +* 主机端口 9000（S3 API）和 9001（控制台）可用，或与自定义端口一致 +* 如果绑定挂载主机目录，目录所有者必须与容器用户匹配——参见[绑定挂载主机目录](#bind-mount-a-host-directory) + +## 2. 拉取镜像 ```bash docker pull rustfs/rustfs:latest ``` -## 2. 创建持久化存储 +## 3. 创建持久化存储 创建命名卷，以便替换容器后对象数据仍然可用： @@ -19,7 +25,7 @@ docker pull rustfs/rustfs:latest docker volume create rustfs-data ``` -## 3. 启动 RustFS +## 4. 启动 RustFS 运行容器前，请替换凭证占位符： @@ -47,7 +53,33 @@ docker run -d \ ::: -## 4. 验证部署 +### 环境变量或命令行参数 + +上面的示例通过环境变量配置 RustFS。你也可以使用命令行参数传入相同的设置；两者同时存在时，命令行参数优先： + +```bash +docker run -d \ + --name rustfs \ + -p 9000:9000 \ + -p 9001:9001 \ + -v rustfs-data:/data \ + rustfs/rustfs:latest \ + --access-key "" \ + --secret-key "" \ + --address :9000 \ + --console-enable \ + /data +``` + +## 5. 绑定挂载主机目录 + +上面的命名卷无需额外设置。如果改用主机目录挂载（`-v /path/on/host:/data`），请注意容器以非 root 用户 `rustfs`（ID `10001`）运行。请确保主机目录的所有者为 `10001`，否则会遇到权限拒绝错误： + +```bash +chown -R 10001:10001 /path/to/host_directory +``` + +## 6. 验证部署 检查容器和 S3 API 健康检查端点： @@ -58,8 +90,106 @@ curl --fail http://localhost:9000/health S3 API 位于 `http://localhost:9000`，控制台位于 `http://localhost:9001`。 +## Docker Compose + +RustFS 官方提供 Docker Compose 安装方式。[`docker-compose.yml`](https://github.com/rustfs/rustfs/blob/main/docker-compose.yml) 文件包含 `grafana`、`prometheus`、`otel-collector` 和 `jaeger` 等服务，主要用于可观测性。如果要一起部署这些服务，请将 [RustFS 代码仓库](https://github.com/rustfs/rustfs)克隆到本地： + +```bash +git clone https://github.com/rustfs/rustfs.git +``` + +在仓库根目录下运行命令： + +```bash +docker compose --profile observability up -d +``` + +compose 文件使用初始化容器为 `rustfs` 授予正确的访问权限：下面的 `rustfs_perms` 服务在 `rustfs` 启动前将挂载卷的所有权更改为 `10001`，并使用 `depends_on` 等待其完成。为了确保日志持久化且可访问，将主机日志目录映射到容器的 `/var/log/rustfs/` 路径： + +```yaml title="docker-compose.yml" + services: + # grant the necessary permissions to RUSTFS volumes path + rustfs_perms: + image: alpine + user: root + volumes: + - /path/to/host_directory/volumes:/fix_path + command: chown -R 10001:10001 /fix_path + + rustfs: + image: rustfs/rustfs:latest + depends_on: + rustfs_perms: + condition: service_completed_successfully + volumes: + - /path/to_host_directory/volumes/data:/data + - /path/to_host_directory/volumes/logs:/var/log/rustfs/ + environment: + - RUSTFS_ADDRESS=":9000" + - RUSTFS_CONSOLE_ADDRESS=":9001" + - RUSTFS_CONSOLE_ENABLE=true + - RUSTFS_OBS_LOGGER_LEVEL=error + - RUSTFS_OBS_LOG_DIRECTORY="/var/log/rustfs/" + + # ... other configurations +``` + +如果只想安装 RustFS，而不安装 Grafana、Prometheus 和其他可观测性服务，请仅启动 `rustfs` 服务（compose 文件将 collector 依赖项标记为可选）： + +```bash +docker compose -f docker-compose.yml up -d rustfs +``` + +这样只会安装并启动 `rustfs-server` 容器。无论只启动 `rustfs-server` 还是完整栈，S3 API 都位于 `http://localhost:9000`，RustFS 控制台位于 `http://localhost:9001`。请在浏览器中打开控制台，使用上面配置的访问密钥和秘密密钥登录。例如使用 `openssl rand -base64 24` 生成强密钥，绝不要将占位符值用于生产环境。 + +对于 Docker Compose，请在 `rustfs` 服务环境或用于变量替换的环境文件中定义唯一的 `RUSTFS_ACCESS_KEY` 和 `RUSTFS_SECRET_KEY`，然后使用 `docker compose up -d rustfs` 重新创建服务。 + +## 多节点部署 + +Docker 默认的桥接网络不支持多节点部署。使用 `--network host`，让每个容器可以直接与其他节点通信。 + +在**每个节点**上运行以下命令： + +```bash +docker run -d \ + --name rustfs \ + --network host \ + -v /mnt/rustfs/data:/data \ + -e RUSTFS_ACCESS_KEY="" \ + -e RUSTFS_SECRET_KEY="" \ + -e RUSTFS_ADDRESS=":9000" \ + -e RUSTFS_CONSOLE_ADDRESS=":9001" \ + -e RUSTFS_CONSOLE_ENABLE=true \ + -e RUSTFS_OBS_LOGGER_LEVEL=error \ + -e RUSTFS_OBS_LOG_DIRECTORY="/var/log/rustfs/" \ + -e RUSTFS_VOLUMES="http://node{1...4}:9000/data/rustfs{0...3}" \ + rustfs/rustfs:latest +``` + +在**每个**节点的 `/etc/hosts` 中添加条目： + +```ini title="/etc/hosts" +192.168.1.1 node1 +192.168.1.2 node2 +192.168.1.3 node3 +192.168.1.4 node4 +``` + +## TLS 配置 + +如果[使用 TLS](../../integration/tls-configured.md)，需要额外挂载证书路径并指向 RustFS： + +```bash +-v /path/to/certs:/certs \ +-e RUSTFS_TLS_PATH=/certs \ +``` + +## 生产环境之前 + +在生产环境部署前，请完成[预安装检查清单](../requirement/checklists/index.md)——硬件、网络、软件和安全。建议使用多节点部署架构、[启用 TLS 加密通信](../../integration/tls-configured.md)、配置日志轮转策略，并设置定期备份策略。 + ## 后续步骤 - [RustFS 控制台](/administration/console) - [配置 S3 客户端](../../developer/examples/aws-cli.md) -- [TLS 配置](../../integration/tls-configured.md) \ No newline at end of file +- [TLS 配置](../../integration/tls-configured.md) diff --git a/content/zh/installation/container/index.md b/content/zh/installation/container/index.md new file mode 100644 index 00000000..67f27ca6 --- /dev/null +++ b/content/zh/installation/container/index.md @@ -0,0 +1,25 @@ +--- +title: "容器" +description: "使用 Docker 或 Podman 运行官方 RustFS 容器镜像。" +--- + +RustFS 是高性能、兼容 S3 的开源分布式对象存储系统。在单节点单磁盘（SNSD）部署模式下，后端使用零纠删码，不提供额外数据冗余，适合本地测试和小规模场景。官方 RustFS 镜像将 RustFS 二进制及其运行环境打包到容器中，一条命令即可启动带持久化存储的服务。 + +容器以非 root 用户 `rustfs`（ID `10001`）运行，因此绑定挂载的主机目录必须由 `10001` 所有，否则会遇到权限拒绝错误。 + +## 容器运行时 + +- [Docker](./docker.md)：运行带持久化存储的单节点实例，并可扩展 Docker Compose、TLS 和多节点网络。 +- [Podman](./podman.md)：以无守护进程的方式运行同一镜像。 + +:::note[目录权限] + +如果使用 `-v` 将主机目录挂载到容器，请确保主机目录的所有者为 `10001`： + +```bash +chown -R 10001:10001 /path/to/host_directory +``` + +::: + +如需在 Kubernetes 中部署，请参阅 [Helm Chart](/installation/cloud-native/helm-chart) 或 [Operator](/installation/cloud-native/operator)。 diff --git a/content/zh/installation/container/index.mdx b/content/zh/installation/container/index.mdx deleted file mode 100644 index 6c298bee..00000000 --- a/content/zh/installation/container/index.mdx +++ /dev/null @@ -1,317 +0,0 @@ ---- -title: "使用 Docker 安装 RustFS" -description: "RustFS Docker 部署。" ---- - -RustFS 是高性能、兼容 S3 的开源分布式对象存储系统。在单节点单磁盘（SNSD）部署模式下，后端使用零纠删码，不提供额外数据冗余，适合本地测试和小规模场景。 -本文基于 RustFS 官方 Linux 二进制软件包，通过自定义 Dockerfile 将 RustFS 及其运行环境打包到容器中，并配置数据卷和环境变量以一键启动服务。 - ---- - -## 1. 前提条件 - -1. **主机要求** - - * 已安装 Docker（≥ 20.10），并能正常拉取镜像和运行容器 - * 本地路径 `/mnt/rustfs/data`（或自定义路径），用于挂载对象数据 - * 管理主机上已安装 [`rc`](/operations/rc)，用于验证流程 -2. **网络和防火墙** - - * 确保主机端口 9000（S3 API）和 9001（控制台）可供外部访问，或与自定义端口一致 - -3. **目录权限** - - * RustFS 容器以 ID 为 `10001` 的非 root 用户 `rustfs` 运行。如果使用 docker 的 `-v` 将主机目录挂载到容器，请确保主机目录的所有者为 `10001`，否则会遇到权限拒绝错误。运行 `chown -R 10001:10001 /path/to/host_directory` 授予必要权限。 - ---- - -## 2. 拉取 RustFS 官方镜像 - -从 Docker Hub 拉取基于 Alpine 的官方镜像： - -```bash -docker pull rustfs/rustfs -``` - ---- - - - -## 3. 运行 RustFS 容器 - -使用上述镜像和配置，按以下方式运行 RustFS SNSD Docker： - -```bash - docker run -d \ - --name rustfs_local \ - -p 9000:9000 \ - -p 9001:9001 \ - -v /mnt/rustfs/data:/data \ - rustfs/rustfs:latest \ - /data -``` - -参数说明： - -* `-p 9000:9000`：将主机端口 9000 映射到容器 -* `-v /mnt/rustfs/data:/data`：挂载数据卷 -* `--name rustfs_local`：自定义容器名称 -* `-d`：在后台运行 - ---- - -### 完整配置示例 - -配置可以通过环境变量（推荐）或命令行参数传入，请选择一种方式；两者同时存在时，命令行参数优先。卷路径（`/data`）始终放在最后。 - - - - -```bash {7,8} -# Use a unique access key and a strong, random secret (e.g. openssl rand -base64 24) -docker run -d \ - --name rustfs \ - -p 9000:9000 \ - -p 9001:9001 \ - -v /mnt/rustfs/data:/data \ - -e RUSTFS_ACCESS_KEY="" \ - -e RUSTFS_SECRET_KEY="" \ - -e RUSTFS_ADDRESS=":9000" \ - -e RUSTFS_CONSOLE_ADDRESS=":9001" \ - -e RUSTFS_CONSOLE_ENABLE=true \ - -e RUSTFS_OBS_LOGGER_LEVEL=error \ - -e RUSTFS_OBS_LOG_DIRECTORY="/var/log/rustfs/" \ - rustfs/rustfs:latest \ - /data -``` - - - - -```bash {8,9} -# Use a unique access key and a strong, random secret (e.g. openssl rand -base64 24) -docker run -d \ - --name rustfs \ - -p 9000:9000 \ - -p 9001:9001 \ - -v /mnt/rustfs/data:/data \ - rustfs/rustfs:latest \ - --access-key "" \ - --secret-key "" \ - --address :9000 \ - --console-enable \ - /data -``` - - - - -### 常用配置组合 - -1. **基本配置**： - ```bash - docker run -d \ - -p 9000:9000 \ - -p 9001:9001 \ - -v /mnt/data:/data \ - rustfs/rustfs:latest \ - /data - ``` - -2. **启用控制台**： - ```bash - docker run -d \ - -p 9000:9000 \ - -p 9001:9001 \ - -v /mnt/data:/data \ - -e RUSTFS_ADDRESS=":9000" \ - -e RUSTFS_CONSOLE_ADDRESS=":9001" \ - -e RUSTFS_CONSOLE_ENABLE=true \ - -e RUSTFS_OBS_LOGGER_LEVEL=error \ - -e RUSTFS_OBS_LOG_DIRECTORY="/var/log/rustfs/" \ - rustfs/rustfs:latest \ - --console-enable \ - /data - ``` - -3. **自定义身份验证密钥**： - ```bash - # Use a unique access key and a strong, random secret (e.g. openssl rand -base64 24) - docker run -d \ - -p 9000:9000 \ - -p 9001:9001 \ - -v /mnt/data:/data \ - -e RUSTFS_ACCESS_KEY="" \ - -e RUSTFS_SECRET_KEY="" \ - rustfs/rustfs:latest \ - --access-key "" \ - --secret-key "" \ - /data - ``` - -### 重要说明 - -1. 端口映射必须对应： - - 服务端口默认为 9000（`-p 9000:9000`） - -2. 数据卷必须持久化： - - `-v /host/path:/container/path` - -3. 环境变量和命令行参数可以混用，但命令行参数优先级更高 - -4. 如果[使用 TLS](../../integration/tls-configured.md)，需要额外挂载证书路径： - - ```bash - -v /path/to/certs:/certs \ - -e RUSTFS_TLS_PATH=/certs \ - ``` - -### 使用 Docker Compose 安装 - -RustFS 官方提供 Docker Compose 安装方式。[`docker-compose.yml`](https://github.com/rustfs/rustfs/blob/main/docker-compose.yml) 文件包含 `grafana`、`prometheus`、`otel-collector` 和 `jaeger` 等多个服务，主要用于可观测性。如果要一起部署这些服务，请将 [RustFS 代码仓库](https://github.com/rustfs/rustfs)克隆到本地： - -```bash -git clone https://github.com/rustfs/rustfs.git -``` - -在根目录下运行命令： - -```bash -docker compose --profile observability up -d -``` - -提供必要的权限。需要使用初始化容器，通过 `depends_on` 关键字为 rustfs 授予正确的访问权限。以下示例将 `rustfs_perms` 服务添加到 `docker-compose.yml` 来处理权限。为了确保日志持久化且可访问，将主机日志目录映射到容器的 `/var/log/rustfs/` 路径： - -```yaml title="docker-compose.yml" - services: - # grant the necessary permissions to RUSTFS volumes path - rustfs_perms: - image: alpine - user: root - volumes: - - /path/to/host_directory/volumes:/fix_path - command: chown -R 10001:10001 /fix_path - - rustfs: - image: rustfs/rustfs:latest - depends_on: - rustfs_perms: - condition: service_completed_successfully - volumes: - - /path/to_host_directory/volumes/data:/data - - /path/to_host_directory/volumes/logs:/var/log/rustfs/ - environment: - - RUSTFS_ADDRESS=":9000" - - RUSTFS_CONSOLE_ADDRESS=":9001" - - RUSTFS_CONSOLE_ENABLE=true - - RUSTFS_OBS_LOGGER_LEVEL=error - - RUSTFS_OBS_LOG_DIRECTORY="/var/log/rustfs/" - - # ... other configurations -``` - -启动后的容器如下： - -```text -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -c13c23fe3d9d rustfs/rustfs:latest "/entrypoint.sh rust…" 6 seconds ago Up 5 seconds (health: starting) 0.0.0.0:9000-9001->9000-9001/tcp, :::9000-9001->9000-9001/tcp rustfs-server -e3f4fc4a83a2 grafana/grafana:latest "/run.sh" 7 seconds ago Up 5 seconds 0.0.0.0:3000->3000/tcp, :::3000->3000/tcp grafana -71ef1b8212cf prom/prometheus:latest "/bin/prometheus --c…" 7 seconds ago Up 5 seconds 0.0.0.0:9090->9090/tcp, :::9090->9090/tcp prometheus -e7db806b2d6f jaegertracing/all-in-one:latest "/go/bin/all-in-one-…" 7 seconds ago Up 5 seconds 4317-4318/tcp, 9411/tcp, 0.0.0.0:14250->14250/tcp, :::14250->14250/tcp, 14268/tcp, 0.0.0.0:16686->16686/tcp, :::16686->16686/tcp jaeger -1897830a2f1e otel/opentelemetry-collector-contrib:latest "/otelcol-contrib --…" 7 seconds ago Up 5 seconds 0.0.0.0:4317-4318->4317-4318/tcp, :::4317-4318->4317-4318/tcp, 0.0.0.0:8888-8889->8888-8889/tcp, :::8888-8889->8888-8889/tcp, 55679/tcp otel-collector -``` - -如果只想安装 RustFS，而不安装 Grafana、Prometheus 和其他可观测性服务，请仅启动 `rustfs` 服务（compose 文件将 collector 依赖项标记为可选）： - -```bash -docker compose -f docker-compose.yml up -d rustfs -``` - -这样只会安装并启动 `rustfs-server` 服务，即 rustfs 容器： - -```text -docker ps -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -e07121ecdd39 rustfs/rustfs:latest "/entrypoint.sh rust…" 2 seconds ago Up 1 second (health: starting) 0.0.0.0:9000-9001->9000-9001/tcp, :::9000-9001->9000-9001/tcp rustfs-server -``` - -无论只启动 `rustfs-server` 还是同时启动可观测性服务，S3 API 都位于 `http://localhost:9000`，RustFS 控制台位于 `http://localhost:9001`。请在浏览器中打开控制台，使用上面配置的访问密钥和秘密密钥（`` / `` 占位符）登录。例如使用 `openssl rand -base64 24` 生成强密钥，绝不要将占位符值用于生产环境。 - -:::warning[立即设置容器凭证] - -在将 RustFS 接入网络前，请设置唯一的 `RUSTFS_ACCESS_KEY` 和 `RUSTFS_SECRET_KEY` 环境变量。任一凭证都不要使用众所周知的 `rustfsadmin` 值。对于 `docker run`，使用 `-e` 传入这两个值。对于 Docker Compose，请在 `rustfs` 服务环境或用于变量替换的环境文件中定义这两个变量，然后使用 `docker compose up -d rustfs` 重新创建服务。 - -::: - -## 4. 验证和访问 - -1. **查看容器状态和日志：** - - ```bash - docker logs rustfs_local - ``` - - 日志应显示服务成功启动并监听端口 9000。 - -2. **测试 S3 API：** - - 使用 `rc` 验证 S3 API： - - ```bash - # Use a unique access key and a strong, random secret (e.g. openssl rand -base64 24) - rc alias set rustfs http://localhost:9000 - rc bucket create rustfs/my-bucket - rc bucket list rustfs/ - ``` - - 如果可以成功创建并列出存储桶，则部署有效。 - -## 5. 多节点 - -Docker 默认的桥接网络不支持多节点部署。使用 `--network host`，让每个容器可以直接与其他节点通信。 - -在**每个节点**上运行以下命令： - -```bash -# Use a unique access key and a strong, random secret (e.g. openssl rand -base64 24) -docker run -d \ - --name rustfs \ - --network host \ - -v /mnt/rustfs/data:/data \ - -e RUSTFS_ACCESS_KEY="" \ - -e RUSTFS_SECRET_KEY="" \ - -e RUSTFS_ADDRESS=":9000" \ - -e RUSTFS_CONSOLE_ADDRESS=":9001" \ - -e RUSTFS_CONSOLE_ENABLE=true \ - -e RUSTFS_OBS_LOGGER_LEVEL=error \ - -e RUSTFS_OBS_LOG_DIRECTORY="/var/log/rustfs/" \ - -e RUSTFS_VOLUMES="http://node{1...4}:9000/data/rustfs{0...3}" \ - rustfs/rustfs:latest -``` - -在**每个**节点的 `/etc/hosts` 中添加条目： -```ini title="/etc/hosts" -192.168.1.1 node1 -192.168.1.2 node2 -192.168.1.3 node3 -192.168.1.4 node4 -``` - -## 6. 其他建议 - -1. 生产环境建议： -- 使用多节点部署架构 -- [启用 TLS 加密通信](../../integration/tls-configured.md) -- 配置日志轮转策略 -- 设置定期备份策略 - -2. 存储建议： -- 使用本地 SSD/NVMe 存储 -- 避免使用网络文件系统（NFS） -- 确保存储目录独占访问 - ---- - -## 总结 - -本文介绍使用 Docker 部署 RustFS 的最佳实践，从单节点单磁盘（SNSD）设置开始，再扩展到多节点部署选项。 \ No newline at end of file diff --git a/content/zh/installation/container/podman.md b/content/zh/installation/container/podman.md index c33620da..b52b5440 100644 --- a/content/zh/installation/container/podman.md +++ b/content/zh/installation/container/podman.md @@ -19,6 +19,16 @@ podman pull docker.io/rustfs/rustfs:latest podman volume create rustfs-data ``` +:::note[绑定挂载主机目录] + +上面的命名卷无需额外设置。如果改用主机目录挂载，请注意容器以非 root 用户 `rustfs`（ID `10001`）运行。请确保主机目录的所有者为 `10001`，否则会遇到权限拒绝错误： + +```bash +chown -R 10001:10001 /path/to/host_directory +``` + +::: + ## 3. 启动 RustFS 运行容器前，请替换凭证占位符： @@ -61,4 +71,4 @@ S3 API 位于 `http://localhost:9000`，控制台位于 `http://localhost:9001` - [RustFS 控制台](/administration/console) - [配置 S3 客户端](../../developer/examples/aws-cli.md) -- [TLS 配置](../../integration/tls-configured.md) \ No newline at end of file +- [TLS 配置](../../integration/tls-configured.md) diff --git a/content/zh/installation/index.md b/content/zh/installation/index.md index eece1c6b..1c675965 100644 --- a/content/zh/installation/index.md +++ b/content/zh/installation/index.md @@ -18,7 +18,7 @@ RustFS 是使用 Rust 编写并采用 Apache 2.0 许可证发布的分布式对 | 目标 | 推荐方式 | 指南 | | - | - | - | -| 在本地计算机上试用 RustFS | 一键安装脚本或容器 | [Linux 快速入门](./linux/quick-start.md) · [容器](./container/index.mdx) | +| 在本地计算机上试用 RustFS | 一键安装脚本或容器 | [Linux 快速入门](./linux/quick-start.md) · [容器](./container/index.md) | | 单服务器生产环境 | SNSD（单磁盘）或 SNMD（多磁盘） | [在 Linux 上安装 RustFS](./linux/index.md) | | 多服务器生产集群 | 完成生产检查清单后使用 MNMD | [多节点多磁盘](./linux/multiple-node-multiple-disk.md) · [检查清单](./requirement/checklists/index.md) | | Kubernetes/云原生 | 容器编排部署 | [云原生](./cloud-native/index.md) | @@ -34,4 +34,4 @@ RustFS 是使用 Rust 编写并采用 Apache 2.0 许可证发布的分布式对 ## 检查清单 -部署任何生产环境前，请完成[安装前检查清单](./requirement/checklists/index.md)，检查硬件、网络、软件和安全性，确保环境符合生产指导要求。 \ No newline at end of file +部署任何生产环境前，请完成[安装前检查清单](./requirement/checklists/index.md)，检查硬件、网络、软件和安全性，确保环境符合生产指导要求。 diff --git a/content/zh/installation/linux/quick-start.md b/content/zh/installation/linux/quick-start.md index 171a62a5..f4103ad6 100644 --- a/content/zh/installation/linux/quick-start.md +++ b/content/zh/installation/linux/quick-start.md @@ -88,5 +88,5 @@ rc object list rustfs/my-bucket - [单节点单磁盘（SNSD）](./single-node-single-disk.md)：开发和小型工作负载 - [单节点多磁盘（SNMD）](./single-node-multiple-disk.md)：单台计算机上的磁盘级容错 - [多节点多磁盘（MNMD）](./multiple-node-multiple-disk.md)：生产级可用性和扩展能力，并完成[安装前检查清单](../requirement/checklists/index.md) -- **偏好使用容器？** 请[使用容器安装](../container/index.mdx) +- **偏好使用容器？** 请[使用容器安装](../container/index.md) - **连接应用程序**：参阅 [SDK 和示例](../../developer/sdk/index.md)