bmmbmm01/sftp repository overview

⁠SFTP with Fail2Ban — Alpine Edge

An SFTP-only Docker image based on Alpine Linux edge (rolling) with OpenSSH, OpenSSL, Fail2Ban, rsyslog, WHOIS and persistent configuration. The standard SSHD profile restricts interactive shells, SSH forwarding, X11 and tunnels while supporting SFTP clients such as FileZilla.

Related Debian image: GitHub sftp-debian⁠ · Docker Hub sftp2⁠. Alpine and Debian are separate images; using one does not update the other.

⁠Features

• Alpine edge packages, with apk upgrade --available during image build.
• Optional AUTO_UPDATE=suite at startup and opt-in periodic updates; running SSHD is not hot-patched.
• Four Fail2Ban jails: sshd, sshd-cipher-mismatch, sshd-banner-fail, and recidive.
• Persistent SSH host keys, user accounts, security logs, Fail2Ban configuration and ban database under /config.
• SFTP chroot homes with writable shares mounted below /home/USERNAME; existing share permissions preserved by default.
• Build and runtime version reporting, health check and security diagnostics.

⁠Build and run

The repository's root Dockerfile builds the Alpine edge image.

git clone https://github.com/bmartino1/sftp-alpine.git
cd sftp-alpine
docker build --pull --no-cache -t sftp-alpine:edge-local .

Use an isolated directory for your first run; don't mount production keys or user data before validation.

mkdir -p ./test-config ./test-share
# Choose a unique admin password for this disposable first boot.
read -rsp "Test admin password: " ADMIN_PASS; echo
export ADMIN_PASS
docker run -d --name sftp-alpine-test \
  --cap-add=NET_ADMIN --cap-add=NET_RAW \
  -p 2222:22 \
  -e TZ=America/Chicago \
  -e AUTO_UPDATE=none \
  -e DEFAULT_ADMIN=true \
  -e ADMIN_USER=admin \
  -e ADMIN_PASS \
  -v "$(pwd)/test-config:/config" \
  -v "$(pwd)/test-share:/home/admin/data" \
  sftp-alpine:edge-local
unset ADMIN_PASS

The example above seeds test-config/sshd/users.conf with the chosen first-boot password. For manual account management, set DEFAULT_ADMIN=false, prepare test-config/sshd/users.conf with a record such as admin:YOUR_UNIQUE_PASSWORD:1000:100:data, and then start the container. Do not commit real passwords, host keys or /config contents.

For Docker Compose, use the repository-root docker-compose.yml⁠. Set ADMIN_PASS in a local, untracked .env file before running docker compose up -d --build. The template builds the local Alpine Dockerfile; remove its build section to pull the published Docker Hub image instead.

⁠Environment variables

Alpine versus Debian admin synchronization (source verified, fresh-build runtime verification still needed): In this Alpine implementation, ADMIN_USER and ADMIN_PASS only seed a missing users.conf when DEFAULT_ADMIN=true. Changing ADMIN_PASS later does not rewrite an existing account. Edit /config/sshd/users.conf and restart to change a persisted password. Similarly, SFTP_USERS is applied at startup but is not persisted to that file. Do not assume Debian sftp2 environment synchronization behavior applies to this image.

⁠Persistent configuration and permissions

Mount the host's application data at /config. Key locations:

Supported account records:

admin:YOUR_UNIQUE_PASSWORD:1000:100:data
user2:ANOTHER_UNIQUE_PASSWORD:1001:100:uploads
user3:ENCRYPTED_PASSWORD_HASH:e:1002:100:uploads

Chroot directories (/home/admin) must remain root:root and non-writable. Mount your files under a child directory (/home/admin/data). Existing host ownership/ACLs are respected unless you explicitly enable SHARE_MOUNT_PERMS=group. Use NET_ADMIN and NET_RAW when you need Fail2Ban's firewall enforcement.

If migrating a running server, preserve both users.conf and the existing SSH host keys. Losing the keys changes the SSH server identity and prompts clients to reverify it.

⁠Updates, verification and security

AUTO_UPDATE=suite upgrades available Alpine edge packages before SSHD starts. Optional AUTO_UPDATE_INTERVAL_HOURS=24 enables periodic checks; changes to OpenSSH require a deliberate restart to run updated binaries and libraries. An old image may return to older installed packages when recreated; rebuild and redeploy regularly.

After starting the container:

docker exec sftp-alpine-test ssh -V
docker exec sftp-alpine-test openssl version
docker exec sftp-alpine-test fail2ban-client status
docker exec sftp-alpine-test sshd -t
docker inspect --format '{{.State.Health.Status}}' sftp-alpine-test

Verify authentication and read/write permissions using a test SFTP client and confirm that Fail2Ban bans block real unwanted connections. A jail showing as running is not itself proof of firewall enforcement. Docker NAT or VPN routing may affect which client IP SSHD sees.

Source code is covered by LICENSE⁠; included Linux packages retain their own licenses. See third-party license notes⁠ and user-management guidance⁠.

For support, use [the Unraid SFTP support thread](https://forums.unraid.net/topic/⁠