Container-based Deployment (Docker/Podman)

This section adapts the saunafs-container repository README for easy reference within the SaunaFS docs. It helps you spin up a demo cluster using Docker or Podman. It is intended for testing, demos, and education—not for production.

Testing and education only

This container setup is designed for demos and playgrounds. It should NOT be used for production data!

Requirements

• Docker and Docker Compose (v2) or Podman and podman-compose
• ~1 GB free disk space recommended for simulating storage replication

Get the container repo

Clone the saunafs-container repository:

git clone https://github.com/leil-io/saunafs-container.git
cd saunafs-container

Builds use the public SaunaFS APT repository and do not require credentials.

Build and run with Docker

Note: On some systems, the buildx plugin may need to be installed first (e.g., Ubuntu):

sudo apt install -y docker-buildx

# Build the shared base image (no credentials required)
docker build \
  -f saunafs-base/Dockerfile \
  -t saunafs-base saunafs-base/

# Build and start all services
docker compose up --build

Build and run with Podman

If you previously created a ./volumes folder while using Docker, delete it before deploying with Podman to avoid permission issues.

# Build the shared base image (no credentials required)
podman build \
  -f saunafs-base/Dockerfile \
  -t saunafs-base saunafs-base/

# Build and start all services
podman-compose up --build

Note: docker compose (v2) or podman-compose is recommended.

Access the CGI monitor

Open the CGI monitor in your browser:

http://localhost:29425/sfs.cgi?masterhost=master&masterport=9421

Data persistence and initialization

This deployment is designed for convenience:

• No pre-committed data. The volumes/ directory is not part of the repo.
• Automatic initialization on first startup: each service will create default configuration files (from /usr/share/doc/saunafs-*/examples/ in the containers) and initialize data directories.
• Persistent data: If you map volumes to standard SaunaFS paths (e.g., /var/lib/saunafs/, /etc/saunafs/), your data and configs persist across restarts. If these are empty initially, they are auto-initialized.
• Chunkserver storage:
  • Chunkservers look for mount points at /mnt/hdd001, /mnt/hdd002, etc.
  • If you provide external volumes mounted to these paths in your docker-compose.yml, they will be used.
  • If not provided, the startup script creates these directories inside the container (volatile storage) and logs a warning. Suitable for testing, not for production.

Cleaning up data

If you used Docker named volumes or host-mounted directories, your data persists after containers stop.

To reset the environment:

• Named volumes:
  • List: docker volume ls
  • Remove: docker volume rm <volume_name>
• Host-mounted directories:
  • If you created a local volumes directory and mapped paths (e.g., ./volumes/master/data:/var/lib/saunafs), delete those directories on your host.

Example cleanup (host-mounted ./volumes/):

# WARNING: Permanently deletes data. Verify the path!
sudo rm -r ./volumes

Be careful with destructive commands

Using rm -r on the wrong path can cause irreversible data loss. Double-check the directory.