DOCSEARCHbyAlgolia
Submit Docs

alpine-ftp-server

repository·master·Indexed 42 days ago

https://github.com/delfer/docker-alpine-ftp-server

A small and flexible Docker image providing an FTP server based on vsftpd running on Alpine Linux. It supports user configuration via the USERS environment variable, passive port range customization, and FTPS (FTP over SSL) integration using certificates from Let's Encrypt.

Tokens
1.1K
Snippets
4
Records
5
Agent score
3%

What's inside alpine-ftp-server

  1. Configure FTPS (FTP over SSL) with Let's Encrypt

    master

    To use FTPS, you must provide paths to a valid SSL certificate and private key via TLS_CERT and TLS_KEY environment variables.

    Steps:

    1. Ensure port 80 is available for Certbot's standalone mode.
    2. Issue a certificate using Certbot.
    3. Mount the certificate directory as read-only (:ro) to the FTP container.
    4. Set the TLS_CERT and TLS_KEY environment variables to the paths of your fullchain.pem and privkey.pem.

    Note: Remember to renew certificates every 3 months using certbot renew.

    # 1. Issue certificate
mkdir -p /etc/letsencrypt
docker run -it --rm \
    -p 80:80 \
    -v "/etc/letsencrypt:/etc/letsencrypt" \
    certbot/certbot certonly \
    --standalone \
    --preferred-challenges http \
    -n --agree-tos \
    --email i@delfer.ru \
    -d ftp.site.domain

# 2. Run FTP server with TLS
docker run -d \
    --name ftp \
    -p "21:21" \
    -p 21000-21010:21000-21010 \
    -v "/etc/letsencrypt:/etc/letsencrypt:ro" \
    -e USERS="one|1234" \
    -e ADDRESS=ftp.site.domain \
    -e TLS_CERT="/etc/letsencrypt/live/ftp.site.domain/fullchain.pem" \
    -e TLS_KEY="/etc/letsencrypt/live/ftp.site.domain/privkey.pem" \
    delfer/alpine-ftp-server

  2. Run the alpine-ftp-server container

    master

    To start a basic FTP server, use docker run with the required port mappings for the FTP service (port 21) and the passive port range. You must also provide the USERS environment variable to define credentials.

    docker run -d \
    -p "21:21" \
    -p 21000-21010:21000-21010 \
    -e USERS="one|1234" \
    -e ADDRESS=ftp.site.domain \
    delfer/alpine-ftp-server

  3. Configure alpine-ftp-server via environment variables

    master

    The server is configured using the following environment variables:

    VariableDescription
    USERSA space and | separated list of users. Format: name|password|[folder][|uid][|gid]. Default: alpineftp|alpineftp
    ADDRESSThe external address (domain or IP) that clients use to connect for passive ports. Should resolve to the server's IP.
    MIN_PORTMinimum port number for passive connections. Default: 21000
    MAX_PORTMaximum port number for passive connections. Default: 21010

  4. Deploy via docker-compose

    master

    When using docker-compose, ensure that port mappings like 21:21 are enclosed in quotes. This is because YAML parsers may interpret numbers in xx:yy format as base-60 values if they are less than 60.

    alpine-ftp-server:
  image: delfer/alpine-ftp-server
  ports:
    - "21:21"
    - 21000-21010:21000-21010
  environment:
    - USERS="one|1234"
    - ADDRESS=ftp.site.domain
  volumes:
    - ...

  5. Define user accounts in the USERS variable

    master

    The USERS environment variable follows a specific delimited format to allow fine-grained control over user directories and permissions.

    Format: name|password|[folder][|uid][|gid]

    Examples:

    • Basic user: user|password (uses default home)
    • User with custom folder: user|password foo|bar|/home/foo
    • User with folder and UID: user|password|/home/user/dir|10000
    • User with folder, UID, and GID: user|password|/home/user/dir|10000|10000
    • User with UID but no folder: user|password||10000
    • User with UID and existing group GID: user|password||10000|82 (e.g., adding to www-data)
    user|password foo|bar|/home/foo
user|password|/home/user/dir|10000
user|password|/home/user/dir|10000|10000
user|password||10000
user|password||10000|82