Fix Docker-based Development Workflow #1031

YGoetschel · 2025-12-06T22:59:59Z

Summary

This PR overhauls the Docker-based development environment to enable a proper source-based workflow (cargo run) and fixes several configuration issues preventing the containers from starting correctly.

Changes

1. Fix docker-compose.yml Configuration

Fixed Shell Expansion: Replaced bash-style brace expansion ({0..3}) with explicit lists for RUSTFS_VOLUMES. The Alpine-based
sh (dash) shell does not support brace expansion, which caused volume creation failures.

Enabled Source-Based Development: Updated the rustfs-dev service to:

Use a new dev target in Dockerfile.source.
Run cargo run instead of a pre-compiled binary.
Mount the local source code (.:/app) and cargo registry (/usr/local/cargo/registry) for incremental compilation.

Fixed Startup Command: Implemented a custom command for rustfs-dev to manually create data directories and pass them as arguments to cargo run. This bypasses the entrypoint.sh limitation when running cargo directly.

Syntax Fixes:
Removed obsolete version field and fixed invalid depends_on references for optional profiles. Corrected relative volume paths to be explicit bind mounts (e.g., ./deploy/...).

2. Update Dockerfile.source

Added a dev stage inheriting from builder to preserve the Rust toolchain for the development container.
Removed a COPY instruction for a non-existent cli/rustfs-gui directory that was breaking the build.

3. Documentation

Added docs/DEVELOPMENT.md: A comprehensive guide on how to set up, run, and debug the docker-based development environment, including instructions for the Console UI.

Updated CONTRIBUTING.md to link to the new development guide.

Verification

Automated Checks

docker compose config passes without errors.
docker compose --profile dev config passes without errors.
make fmt passed (code formatting compliance).

Manual Verification
Startup: Ran docker compose --profile dev up rustfs-dev. Container built and started successfully.
Functionality:

Verified S3 API health: curl http://localhost:9010/health -> 200 OK.
Verified Console UI: curl http://localhost:9011/rustfs/console/index.html -> 200 OK.
Hot Reload: Confirmed that restarting the container (docker compose --profile dev restart rustfs-dev) triggers a recompilation of the mounted source code.
UI Assets: Verified that running scripts/static.sh and rebuilding correctly embeds the Console UI assets.

Related Issues

Fixes VolumeNotFound error on startup.
Fixes docker compose validation errors.

CLAassistant · 2025-12-06T23:00:07Z

All committers have signed the CLA.

docker-compose.yml

Copilot

Pull request overview

This PR fixes the Docker-based development environment by addressing shell expansion issues, enabling source-based development workflows with cargo run, and updating documentation to guide developers through the setup process.

Key Changes:

Fixed Alpine shell incompatibility by replacing brace expansion syntax with explicit comma-separated volume lists
Added a new dev stage in Dockerfile.source to preserve the Rust toolchain for development containers
Created comprehensive development documentation with setup and troubleshooting instructions

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 6 comments.

File	Description
docs/DEVELOPMENT.md	New comprehensive guide for Docker-based local development workflow
docker-compose.yml	Fixed volume environment variables, added dev service configuration with custom command for cargo run, and corrected volume mount paths
Dockerfile.source	Added dev stage inheriting from builder and removed reference to non-existent cli/rustfs-gui directory
CONTRIBUTING.md	Added reference link to new development guide

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

docker-compose.yml

docs/DEVELOPMENT.md

docker-compose.yml

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

…point.sh

Copilot

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 6 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

docker-compose.yml

entrypoint.sh

Dockerfile.source

Copilot · 2025-12-08T02:03:16Z

docs/DEVELOPMENT.md

+If you modify `Cargo.toml` or `Cargo.lock`, you generally need to rebuild the Docker image to update the cached dependencies layer:
+
+```bash
+docker compose --profile dev build rustfs-dev
+```


The statement about needing to rebuild the Docker image when modifying Cargo.toml or Cargo.lock is misleading. Since the source code is mounted at /app and the application runs via cargo run, changes to Cargo.toml will be picked up on container restart without needing to rebuild the image. The image rebuild is only necessary if the dependency pre-fetching layer needs to be updated for better caching, but it's not strictly required for the changes to take effect.

entrypoint.sh

…into fix/docker-deployment

houseme · 2025-12-09T02:41:36Z

@YGoetschel Wait until we verify the changes to entrypoint.sh. Thank you ~

Copilot

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-12-09T02:46:44Z

entrypoint.sh


+  VOLUME_LIST=""
+  for vol in $VOLUME_LIST_RAW; do
+      # Helper to manually expand {N..M} since sh doesn't support it on variables


The comment says "Helper to manually expand {N..M}" but this is somewhat misleading - this is the main implementation for brace expansion, not just a helper. Consider updating the comment to: "Manually expand {N..M} brace notation since sh doesn't support it" for clarity.

Suggested change

# Helper to manually expand {N..M} since sh doesn't support it on variables

# Manually expand {N..M} brace notation since sh doesn't support it

Copilot · 2025-12-09T02:46:45Z

entrypoint.sh

+                 i=$((i+1))
+               done
+           else
+               # Fallback if not numbers


[nitpick] The comment "Fallback if not numbers" could be more descriptive. Consider: "Fallback if START or END are not valid numbers - keep the original pattern unchanged".

Suggested change

# Fallback if not numbers

# Fallback if START or END are not valid numbers - keep the original pattern unchanged

Copilot · 2025-12-09T02:46:45Z

docs/DEVELOPMENT.md

+The development image uses `entrypoint.sh` to parse the `RUSTFS_VOLUMES` environment variable (supporting `{N..M}` syntax), create the directories, and pass them to `cargo run`. Ensure your `RUSTFS_VOLUMES` variable is correctly formatted.
+
+### Slow Initial Build
+This is expected. The `dev` stage in `Dockerfile.source` compiles all dependencies from scratch. Because the `/usr/local/cargo/registry` is mounted as a volume, these compiled artifacts are preserved between restarts, making future builds fast.


This statement is technically incorrect. The /usr/local/cargo/registry volume preserves the crates.io index and downloaded crate archives, not compiled artifacts. Compiled artifacts are in the target/ directory, which is preserved on the host via the source mount (.:/app). Consider rewording to: "Because the source code (including target/) is mounted from the host and the cargo registry is cached in a volume, both downloaded dependencies and compiled artifacts are preserved between restarts, making future builds fast."

Suggested change

This is expected. The `dev` stage in `Dockerfile.source` compiles all dependencies from scratch. Because the `/usr/local/cargo/registry` is mounted as a volume, these compiled artifacts are preserved between restarts, making future builds fast.

This is expected. The `dev` stage in `Dockerfile.source` compiles all dependencies from scratch. Because the source code (including `target/`) is mounted from the host and the cargo registry is cached in a volume, both downloaded dependencies and compiled artifacts are preserved between restarts, making future builds fast.

majinghe · 2025-12-09T04:49:42Z

@houseme I have tested the change. Steps is as below

checkout the code

build the docker image

docker build -t dllhb/pr-1031:latest -f Dockerfile . --no-cache

testing on container condition
testing on kubernetes condition

RustFS instance can run and bucket/ak & sk creation works fine.

majinghe · 2025-12-08T03:25:28Z

docker-compose.yml

-          "sh", "-c",
-          "curl -f http://localhost:9000/health && curl -f http://localhost:9001/rustfs/console/health"
-        ]
+      test: [ "CMD", "sh", "-c", "curl -f http://localhost:9000/health && curl -f http://localhost:9001/rustfs/console/health" ]


The change seems same with old style. In addition, old style is more readable, I think.

test: [ "CMD", "sh", "-c", "curl -f http://localhost:9000/health && curl -f http://localhost:9001/rustfs/console/health" ]

@YGoetschel FYI

majinghe · 2025-12-08T03:26:01Z

docker-compose.yml

-          "sh", "-c",
-          "curl -f http://localhost:9000/health && curl -f http://localhost:9001/rustfs/console/health"
-        ]
+      test: [ "CMD", "sh", "-c", "curl -f http://localhost:9000/health && curl -f http://localhost:9001/rustfs/console/health" ]


Same with above.

@YGoetschel FYI

fix docker based dev workflow

b1f3861

houseme requested review from Copilot and majinghe December 7, 2025 09:44

Copilot started reviewing on behalf of houseme December 7, 2025 09:44 View session

houseme reviewed Dec 7, 2025

View reviewed changes

docker-compose.yml Outdated Show resolved Hide resolved

Copilot AI reviewed Dec 7, 2025

View reviewed changes

YGoetschel and others added 6 commits December 7, 2025 12:21

Update docker-compose.yml

b5dfc55

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update docs/DEVELOPMENT.md

81bef62

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Merge branch 'main' into fix/docker-deployment

83cef0f

fix wrong numbering

8daa3f9

re-enable parameter expansion and fix docker brace expansion in entry…

7797c1e

…point.sh

Merge branch 'main' into fix/docker-deployment

a86390e

houseme requested a review from Copilot December 8, 2025 01:57

Copilot started reviewing on behalf of houseme December 8, 2025 01:57 View session

Copilot AI reviewed Dec 8, 2025

View reviewed changes

YGoetschel and others added 3 commits December 8, 2025 11:13

improve brace expansion regex to only capture integers

b9e15a8

Merge branch 'fix/docker-deployment' of github.com:YGoetschel/rustfs …

eafe4f4

…into fix/docker-deployment

Merge branch 'main' into fix/docker-deployment

9f43f0c

YGoetschel requested a review from houseme December 8, 2025 16:25

houseme requested a review from Copilot December 9, 2025 02:39

Copilot started reviewing on behalf of houseme December 9, 2025 02:39 View session

Copilot AI reviewed Dec 9, 2025

View reviewed changes

majinghe reviewed Dec 10, 2025

View reviewed changes

Merge branch 'main' into fix/docker-deployment

0cb9482

	# Helper to manually expand {N..M} since sh doesn't support it on variables
	# Manually expand {N..M} brace notation since sh doesn't support it

	# Fallback if not numbers
	# Fallback if START or END are not valid numbers - keep the original pattern unchanged

	This is expected. The `dev` stage in `Dockerfile.source` compiles all dependencies from scratch. Because the `/usr/local/cargo/registry` is mounted as a volume, these compiled artifacts are preserved between restarts, making future builds fast.
	This is expected. The `dev` stage in `Dockerfile.source` compiles all dependencies from scratch. Because the source code (including `target/`) is mounted from the host and the cargo registry is cached in a volume, both downloaded dependencies and compiled artifacts are preserved between restarts, making future builds fast.

Fix Docker-based Development Workflow #1031

Are you sure you want to change the base?

Fix Docker-based Development Workflow #1031

Conversation

YGoetschel commented Dec 6, 2025

Summary

Changes

2. Update Dockerfile.source

3. Documentation

Verification

Related Issues

Uh oh!

CLAassistant commented Dec 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Dec 8, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

houseme commented Dec 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Dec 9, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 9, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 9, 2025

Choose a reason for hiding this comment

Uh oh!

majinghe commented Dec 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

majinghe Dec 8, 2025

Choose a reason for hiding this comment

Uh oh!

majinghe Dec 9, 2025

Choose a reason for hiding this comment

Uh oh!

majinghe Dec 8, 2025

Choose a reason for hiding this comment

Uh oh!

majinghe Dec 9, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

CLAassistant commented Dec 6, 2025 •

edited

Loading

houseme commented Dec 9, 2025 •

edited

Loading

majinghe commented Dec 9, 2025 •

edited

Loading