Skip to content

docs(installation): add SwarmCLI chart guide for Docker Swarm - #185

Merged
houseme merged 15 commits into
rustfs:mainfrom
Eldara-Tech:docs/installation-docker-swarm
Nov 18, 2026
Merged

houseme merged 15 commits into
rustfs:mainfrom
Eldara-Tech:docs/installation-docker-swarm

Conversation

@clangenb

Copy link
Copy Markdown
Contributor

Summary

Adds a SwarmCLI Chart page under Installation → Cloud Native, next to the Helm chart and the Operator. It deploys RustFS on Docker Swarm, as a single-node service or a distributed, erasure-coded cluster, with the open-source rustfs chart and SwarmCLI, a Helm-inspired package manager for Docker Swarm.

The root credentials are Docker secrets, which RustFS reads from files through RUSTFS_ACCESS_KEY_FILE / RUSTFS_SECRET_KEY_FILE (rustfs/src/config/cli.rs). Neither value ends up in the service definition or in docker inspect. None of the existing container pages covers the *_FILE variables yet. The page also shows what the chart adds over a hand-written stack file: upgrades you can preview and roll back, HTTPS and Console single sign-on through the companion Traefik chart, rollouts checked against /health/ready, and, in distributed mode, upgrades that roll one peer at a time.

Disclosure: I'm involved with Eldara Tech, which maintains the chart and SwarmCLI. The page says that both are maintained outside the RustFS project.

Changes

  • installation/cloud-native/swarmcli-chart.md (new), with the same structure as container/podman.md and the install split into standalone and distributed mode like the Helm guide's. It opens with five highlights of what the chart adds. The numbered steps are prerequisites (SwarmCLI 2.2.0, the chart's floor since v0.2.0), Docker secrets, chart repository, install standalone mode, install distributed mode (one node label per peer, distributed-values.yaml, and a "choose the topology before installation" warning), and verify (curl --fail http://localhost:9000/health/ready for standalone, /minio/health/cluster from rustfs-net for distributed). After them come upgrade and roll back (including the one-peer-at-a-time cluster upgrade and the full stop a cluster's credential rotation needs), exposure modes (S3 API and Console set separately, linking the Traefik chart for the traefik mode), key values,
    uninstall, and next steps.
  • installation/cloud-native/meta.json: adds swarmcli-chart to the sidebar, after the Operator.
  • installation/index.md: adds Docker Swarm to the "Change the default credentials" warning.
  • index.mdx (home page): adds an "Install with the SwarmCLI chart" card, modelled on "Install with Helm", in the empty eighth slot of the Self Host grid, linking to the new page. Its icon is the SwarmCLI terminal mark (LuTerminal from react-icons/lu), added to BrandLogo with a light and a dark colour in src/app.css.

The page sticks to the standard example values: <your-access-key> / <your-secret-key>, my-bucket, us-east-1, path-style addressing, and ports 9000/9001.

Locales

All five locale directories are covered: en, zh, de, fr, ja.

  • swarmcli-chart.md is translated in zh, de, fr and ja, following the glossaries in .agents/skills/localize-rustfs-docs/references. Code blocks are byte-identical to English.
  • The one-line addition to installation/index.md is translated in zh, de, fr and ja, now that upstream has translated the rest of that page.
  • The home-page card is translated in all five locales.

Checks

  • npm run docs:check: OK. All checks pass, including locale parity and identical code blocks.
  • npm run build: OK, 3805 files generated.
  • npm run test:search (21) and npm run test:worker (16): all pass.
  • Rendered every values file and --set combination on the page with SwarmCLI v2.2.0 against rustfs chart v0.2.0 (swarmcli charts template): the service, volume, alias and node-label names the page uses match the render.
  • npm run types:check: the same 18 errors as on main, all in worker.mjs / scripts/. None come from this change.
  • audit-locales.mjs --locales de,fr,ja: no findings for the new page, the Cloud Native sidebar or the home-page card.
  • Ran the page's commands against rustfs chart v0.2.0 (RustFS 1.0.1) on a Docker Swarm, in standalone mode and in distributed mode on four nodes. Distributed mode has so far run only on a single-node swarm, in the chart's CI and locally; host-mode publishing and more than one drive per peer are render-only there.

Add installation/container/swarm.md: deploy a single-node RustFS service
on Docker Swarm with the swarmcli rustfs chart, reading the root
credentials from Docker secrets through RUSTFS_ACCESS_KEY_FILE and
RUSTFS_SECRET_KEY_FILE. Covers the secrets, the data-node label, the
install, verification, the S3 API / Console exposure modes, the key
chart values, and uninstalling.

Link it from the container sidebar and overview, and add Docker Swarm
to the credentials warning on the installation overview. zh is
translated; de, fr and ja carry the English text, as for docker.md.
Replace the English fallback text of installation/container/swarm.md in
content/de, content/fr and content/ja with translations that follow the
locale glossaries in .agents/skills/localize-rustfs-docs/references.
Code blocks, identifiers and values are unchanged from English.
… guide

The released rustfs chart (rustfs/v0.1.0) adds the network alias
<release>-rustfs on rustfs-net. Point overlay clients at it instead of
the stack's service name <release>_rustfs: AWS SDK for Java clients
reject a host name that contains '_'. Updated in every locale.
Fills the empty eighth slot in every locale and links to the Swarm guide.
The icon is the SwarmCLI terminal mark (LuTerminal, same geometry).
Mirrors the Helm card, which names the tool and its chart; the
description keeps Docker Swarm so Swarm users still find it.
…Chart

It installs a chart with a package tool, like the Helm chart beside it,
and Cloud Native is the overview's home for container orchestration.
Container's index and menu go back to Docker and Podman only.
Highlights secrets, versioned upgrades and rollbacks, Traefik HTTPS and
health-checked rollouts; adds Upgrade and roll back and the traefik link.
Fixes the minimum SwarmCLI version (list --set needs 1.13.0), probes
/health/ready, and names the unlabelled-node symptom.
rustfs chart v0.2.0 adds mode: distributed and needs SwarmCLI 2.2.0.
Split the install into standalone and distributed steps like the Helm
guide, cover the cluster's rolling upgrade and full-stop credential
rotation, and scope the single-node text, key values and uninstall.
…de, fr and ja

Code blocks are byte-identical to English; unchanged sentences keep
their reviewed translations.
Takes upstream through 8d4806d. Keeps upstream's de, fr and ja
installation index and adds the Docker Swarm credentials bullet in each
language; keeps the Sealos, Elestio and SwarmCLI icon entries side by side.
… ja glossaries

French takes identifiants, a narrow no-break space before : and ;, and the
bucket and path-style glosses; German takes Zugangsdaten and the Path-Style
gloss; Japanese takes パススタイルアクセス.
@vercel

vercel Bot commented Oct 20, 2026

Copy link
Copy Markdown

@clangenb is attempting to deploy a commit to the overtrue's projects Team on Vercel.

A member of the Team first needs to authorize it.

@axkaj

axkaj commented Oct 29, 2026

Copy link
Copy Markdown

nice feature, hope to see it soon in the doc.

@clangenb

Copy link
Copy Markdown
Contributor Author

Hey @majinghe may I ask you to have a look at this PR? We believe that we do add some value here by adding this installation method.

Follow rustfs#189: the page title names the task ("Install RustFS with the
SwarmCLI chart") in every locale, as the Helm and Operator install pages
do, while the sidebar keeps the short "SwarmCLI Chart" label through a
link entry in meta.json.
@clangenb
clangenb force-pushed the docs/installation-docker-swarm branch from 1c0d330 to b6af093 Compare November 13, 2026 12:53
@clangenb

Copy link
Copy Markdown
Contributor Author

We have merged a README change in rustfs: rustfs/rustfs#9405.

So I think it would be nice to merge this one soon, as there is a dead link in that README until we merge this PR too.

@clangenb

Copy link
Copy Markdown
Contributor Author

@houseme allow me to tag you here, as you were the one who shows some activity in the rustfs repository. :)

@houseme
houseme requested review from majinghe and a balanced review from Copilot and removed request for majinghe November 15, 2026 10:19

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The storage-class claims need qualification because REDUCED_REDUNDANCY objects require three of four peers for reads, making the stated two-peer failure tolerance misleading across all five translations.

1 open issue
What changed in this PR

Adds Docker Swarm installation documentation alongside the existing Helm and Operator guides, using the third-party SwarmCLI chart maintained by Eldara Tech.

Changes:

  • Documents standalone and distributed deployment, Docker secrets, verification, upgrades, rollback, exposure, and cleanup.
  • Adds the guide, navigation entries, home-page cards, and credential guidance across English, Chinese, Japanese, French, and German.
  • Adds a SwarmCLI icon with light and dark theme colors.
File Description
src/​components/​brand-logo.tsx Registers the SwarmCLI terminal icon.
src/​app.css Adds light and dark icon colors.
content/​zh/​installation/​index.md Adds Docker Swarm credential guidance.
content/​zh/​installation/​cloud-native/​swarmcli-chart.md Adds the Chinese deployment guide.
content/​zh/​installation/​cloud-native/​meta.json Adds the Chinese sidebar link.
content/​zh/​index.mdx Adds the Chinese installation card.
content/​ja/​installation/​index.md Adds Docker Swarm credential guidance.
content/​ja/​installation/​cloud-native/​swarmcli-chart.md Adds the Japanese deployment guide.
content/​ja/​installation/​cloud-native/​meta.json Adds the Japanese sidebar link.
content/​ja/​index.mdx Adds the Japanese installation card.
content/​fr/​installation/​index.md Adds Docker Swarm credential guidance.
content/​fr/​installation/​cloud-native/​swarmcli-chart.md Adds the French deployment guide.
content/​fr/​installation/​cloud-native/​meta.json Adds the French sidebar link.
content/​fr/​index.mdx Adds the French installation card.
content/​en/​installation/​index.md Adds Docker Swarm credential guidance.
content/​en/​installation/​cloud-native/​swarmcli-chart.md Adds the English deployment guide.
content/​en/​installation/​cloud-native/​meta.json Adds the English sidebar link.
content/​en/​index.mdx Adds the English installation card.
content/​de/​installation/​index.md Adds Docker Swarm credential guidance.
content/​de/​installation/​cloud-native/​swarmcli-chart.md Adds the German deployment guide.
content/​de/​installation/​cloud-native/​meta.json Adds the German sidebar link.
content/​de/​index.mdx Adds the German installation card.

Review effort: Balanced

clangenb and others added 2 commits November 15, 2026 21:48
REDUCED_REDUNDANCY objects get one parity shard on four peers, so their
reads survive only one peer down; the two-peer claim holds for STANDARD.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01J2mZovbZKmkuBQ8h5uU3kb
@clangenb

Copy link
Copy Markdown
Contributor Author

@houseme I have fixed the documentation according to your review.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues were identified for the Docker Swarm installation documentation and supporting navigation and icon updates.

No open issues 🎉

1 resolved since last review

Review effort: Balanced

@houseme
houseme merged commit 80b46ed into rustfs:main Nov 18, 2026
2 of 3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants