bfren/ftps repository overview

⁠FTPS

Docker Hub⁠ - Quay.io⁠ - bfren ecosystem⁠

⁠Introduction

An FTP server that only accepts encrypted connections (FTPS - FTP over TLS), for devices and apps that can't use SFTP. It runs vsftpd⁠ with one user, kept inside /files, and creates a self-signed certificate if you don't provide one.

It is built on Alpine + S6⁠, with vsftpd from Alpine's packages.

⁠Quickstart

services:
  ftps:
    image: quay.io/bfren/ftps:5.2
    restart: unless-stopped
    ports:
      - "0.0.0.0:21:21"
      - "0.0.0.0:18700-18710:18700-18710"
    environment:
      - BF_FTPS_EXTERNAL_URI=ftp.example.com
      - BF_FTPS_VSFTPD_USER=fred
      - BF_FTPS_VSFTPD_PASS=${FTPS_PASS}
    volumes:
      - ./v/files:/files
      - ./v/ssl:/ssl

Run docker compose up -d, then connect with an FTP client, e.g. in FileZilla or WinSCP:

Accept the certificate when the client asks - it is self-signed unless you provide your own.

⁠Features

• 🔐 Encryption required for logins and file transfers
• 📁 One user, kept inside /files
• 📜 Self-signed certificate created on first start, or use your own
• 🌐 Passive mode with a fixed port range, for firewalls and NAT
• 🩺 Health check that logs in and uploads a file
• 🧪 Built-in tests

⁠Tags

Images are published to Docker Hub (bfren/ftps) and Quay.io (quay.io/bfren/ftps) for linux/amd64, linux/arm/v7 and linux/arm64, with vsftpd 3.0.5 on Alpine 3.24.

⁠Configuration

⁠Ports

Publish the whole passive range, with the same numbers on the host and in the container.

⁠Volumes

⁠Environment Variables

See Alpine + S6⁠ for BF_DEBUG, BF_TZ and the other base image variables.

⁠How It Works

On every start:

1. The user, password and external address are checked - the container stops if any are missing.
2. The user is created (if it doesn't exist yet) with /files as its home, and given /files.
3. If /ssl/vsftpd.pem doesn't exist, a self-signed certificate valid for ten years is created there.
4. vsftpd.conf is generated, and vsftpd runs under S6. The container stops if it crashes.

Logins and file transfers must be encrypted, the user is kept inside /files (chroot), and anonymous logins are refused. Uploaded files are readable only by the user (umask 077).

In passive mode the client opens a second connection for each transfer, to a port in the passive range, at the address the server gives it - BF_FTPS_EXTERNAL_URI (looked up when vsftpd starts) or BF_FTPS_EXTERNAL_IP. That address must reach the server from the client's side.

The health check (every 30 seconds) logs in as the user with lftp, uploads a small file and deletes it.

⁠Using your own certificate

Put a PEM file containing both the certificate and its private key at /ssl/vsftpd.pem, then restart. Set BF_FTPS_LFTP_VERIFY_CERT=yes if the certificate is trusted for 127.0.0.1.

⁠Testing

./test.nu   # builds the image and runs /test
./run.sh    # builds the image and opens a shell, with the ports published on 127.0.0.1

/test runs this image's tests alongside the base images' tests: the environment checks, creating the certificate, the generated vsftpd.conf and lftp.conf, and the installed vsftpd version.

⁠Troubleshooting

⁠The container stops straight after starting

Check docker logs <container> - BF_FTPS_VSFTPD_USER, BF_FTPS_VSFTPD_PASS, and BF_FTPS_EXTERNAL_URI or BF_FTPS_EXTERNAL_IP must all be set.

⁠Logging in works, but listing files times out

The passive connection can't get through. Check the whole port range is published and allowed by your firewall, and that BF_FTPS_EXTERNAL_* is the address clients use to reach the server.

⁠I changed the password but the old one still works

The user is only created once, so changes are ignored until the container is recreated (docker compose up -d --force-recreate).

⁠The client says the certificate isn't trusted

It is self-signed. Accept it, or use your own certificate⁠.

⁠FAQs

⁠Can I have more than one user?

No - one user per container. Run another container (with different ports) for another user.

⁠What's the difference between FTPS and SFTP?

FTPS is FTP with TLS encryption. SFTP is a different protocol, part of SSH. This image only supports FTPS.

⁠Licence

⁠Copyright