{"id":13437421,"url":"https://github.com/stilliard/docker-pure-ftpd","last_synced_at":"2025-05-14T19:02:57.374Z","repository":{"id":17513751,"uuid":"20301699","full_name":"stilliard/docker-pure-ftpd","owner":"stilliard","description":"Docker Pure-ftpd Server","archived":false,"fork":false,"pushed_at":"2025-01-20T08:33:48.000Z","size":129,"stargazers_count":866,"open_issues_count":32,"forks_count":322,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-03-30T20:01:40.386Z","etag":null,"topics":["debian-jessie","docker","ftp","ftpd","ftpd-server"],"latest_commit_sha":null,"homepage":"https://hub.docker.com/r/stilliard/pure-ftpd/","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stilliard.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":".github/SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"stilliard","patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":["https://www.buymeacoffee.com/stilliard"]}},"created_at":"2014-05-29T17:14:49.000Z","updated_at":"2025-03-28T08:40:31.000Z","dependencies_parsed_at":"2025-02-28T14:11:59.019Z","dependency_job_id":"2eef8031-21ce-4e2c-8a31-ac16774abdb5","html_url":"https://github.com/stilliard/docker-pure-ftpd","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stilliard%2Fdocker-pure-ftpd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stilliard%2Fdocker-pure-ftpd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stilliard%2Fdocker-pure-ftpd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stilliard%2Fdocker-pure-ftpd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stilliard","download_url":"https://codeload.github.com/stilliard/docker-pure-ftpd/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247550672,"owners_count":20956985,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["debian-jessie","docker","ftp","ftpd","ftpd-server"],"created_at":"2024-07-31T03:00:56.829Z","updated_at":"2025-04-06T21:03:21.068Z","avatar_url":"https://github.com/stilliard.png","language":"Shell","funding_links":["https://github.com/sponsors/stilliard","https://www.buymeacoffee.com/stilliard"],"categories":["HarmonyOS","Shell"],"sub_categories":["Windows Manager"],"readme":"Docker Pure-ftpd Server\n============================\nhttps://hub.docker.com/r/stilliard/pure-ftpd/\n\n![Docker Automated build](https://img.shields.io/docker/automated/stilliard/pure-ftpd)\n[![Docker Pulls](https://img.shields.io/docker/pulls/stilliard/pure-ftpd.svg)](https://hub.docker.com/r/stilliard/pure-ftpd/)\n[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fstilliard%2Fdocker-pure-ftpd.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2Fstilliard%2Fdocker-pure-ftpd?ref=badge_shield)\n[![Sponsor Project](https://img.shields.io/badge/%E2%99%A5-Sponsor_Project-blueviolet)](https://github.com/sponsors/stilliard)\n\n\n----------------------------------------\n\n#### Check out our [basic example workflow](https://github.com/stilliard/docker-pure-ftpd/wiki/Basic-example-walk-through) \u0026 our [slightly more advanced workflow with tls \u0026 an auto created user](https://github.com/stilliard/docker-pure-ftpd/wiki/Advanced-example-walk-through-with-TLS-\u0026-automatic-user-account).\n\n----------------------------------------\n\nPull down latest version with docker:\n```bash\ndocker pull stilliard/pure-ftpd\n```\n\n**Often needing to run as `sudo`, e.g. `sudo docker pull stilliard/pure-ftpd`**\n\n----------------------------------------\n\n**If you want to make changes, my advice is to either change the run command when running it or extend this image to make any changes rather than forking the project.**  \nThis is because rebuilding the entire docker image via a fork can be *very* slow as it rebuilds the entire pure-ftpd package from source. \n\nTo change the command run on start you could use the `command:` option if using `docker-compose`, or with [`docker run`](https://docs.docker.com/engine/reference/run/) directly you could use:\n\n```\ndocker run --rm -d --name ftpd_server -p 21:21 -p 30000-30009:30000-30009 stilliard/pure-ftpd bash /run.sh -c 30 -C 10 -l puredb:/etc/pure-ftpd/pureftpd.pdb -E -j -R -P localhost -p 30000:30059\n```\n\nTo extend it you can create a new project with a `DOCKERFILE` like so:\n\n```\nFROM stilliard/pure-ftpd\n\n# e.g. you could change the defult command run:\nCMD /run.sh -c 30 -C 10 -l puredb:/etc/pure-ftpd/pureftpd.pdb -E -j -R -P $PUBLICHOST -p 30000:30059\n```\n\n*Then you can build your own image, `docker build --rm -t my-pure-ftp .`, where my-pure-ftp is the name you want to build as*\n\n----------------------------------------\n\nStarting it \n------------------------------\n\n`docker run -d --name ftpd_server -p 21:21 -p 30000-30009:30000-30009 -e \"PUBLICHOST=localhost\" stilliard/pure-ftpd`\n\n*Or for your own image, replace stilliard/pure-ftpd with the name you built it with, e.g. my-pure-ftp*\n\nYou can also pass ADDED_FLAGS as an env variable to add additional options such as --tls to the pure-ftpd command.  \ne.g. ` -e \"ADDED_FLAGS=--tls=2\" `\n\n\nOperating it\n------------------------------\n\n`docker exec -it ftpd_server /bin/bash`\n\nSetting runtime FTP user\n------------------------------\n\nTo create a user on the ftp container, use the following environment variables: `FTP_USER_NAME`, `FTP_USER_PASS` and `FTP_USER_HOME`.\n\n`FTP_USER_HOME` is the root directory of the new user.\n\nExample usage:\n\n`docker run -e FTP_USER_NAME=bob -e FTP_USER_PASS=12345 -e FTP_USER_HOME=/home/bob stilliard/pure-ftpd`\n\nIf you wish to set the `UID` \u0026 `GID` of the FTP user, use the `FTP_USER_UID` \u0026 `FTP_USER_GID` environment variables.\n\nUsing different passive ports\n------------------------------\n\nTo use passive ports in a different range (*eg*: `10000-10009`), use the following setup:\n\n`docker run -e FTP_PASSIVE_PORTS=10000:10009 --expose=10000-10009 -p 21:21 -p 10000-10009:10000-10009`\n\nYou may need the `--expose=` option, because default passive ports exposed are `30000` to `30009`.\n\nExample usage once inside\n------------------------------\n\nCreate an ftp user: `e.g. bob with chroot access only to /home/ftpusers/bob`\n```bash\npure-pw useradd bob -f /etc/pure-ftpd/passwd/pureftpd.passwd -m -u ftpuser -d /home/ftpusers/bob\n```\n*No restart should be needed.*\n\n*If you have any trouble with volume permissions due to the **uid** or **gid** of the created user you can change the **-u** flag for the uid you would like to use and/or specify **-g** with the group id as well. For more information see issue [#35](https://github.com/stilliard/docker-pure-ftpd/issues/35#issuecomment-325583705).*\n\nMore info on usage here: https://download.pureftpd.org/pure-ftpd/doc/README.Virtual-Users\n\n\nTest your connection\n-------------------------\nFrom the host machine:\n```bash\nftp -p localhost 21\n```\n\n-------------------------\n\nDocker compose\n-------------------------\nDocker compose can help you simplify the orchestration of your containers.   \nWe have a simple [example of the docker compose](https://github.com/stilliard/docker-pure-ftpd/blob/master/docker-compose.yml).  \n\u0026 here's a [more detailed example using wordpress](https://github.com/stilliard/docker-pure-ftpd/wiki/Docker-stack-with-Wordpress-\u0026-FTP) with ftp using this image.\n\n-------------------------\n\nMax clients\n-------------------------\nBy default we set 5 max clients at once, but you can increase this by using the following environment variable `FTP_MAX_CLIENTS`, e.g. to `FTP_MAX_CLIENTS=50` and then also increasing the number of public ports opened from `FTP_PASSIVE_PORTS=30000:30009` `FTP_PASSIVE_PORTS=30000:30099`. You'll also want to open those ports when running docker run.\nIn addition you can specify the maximum connections per ip by setting the environment variable `FTP_MAX_CONNECTIONS`. By default the value is 5.\n\nAll Pure-ftpd flags available:\n--------------------------------------\nhttps://linux.die.net/man/8/pure-ftpd\n\nLogs\n-------------------------\nTo get verbose logs add the following to your `docker run` command:\n```\n-e \"ADDED_FLAGS=-d -d\"\n```\n\nThen the logs will be redirected to the stdout of the container and captured by the docker log collector.\nYou can watch them with `docker logs -f ftpd_server`\n\nOr, if you exec into the container you could watch over the log with `tail -f /var/log/messages`\n\nWant a transfer log file? add the following to your `docker run` command:\n```bash\n-e \"ADDED_FLAGS=-O w3c:/var/log/pure-ftpd/transfer.log\"\n```\n\n----------------------------------------\n\nTags available for different versions\n--------------------------------------\n\n**Latest versions**\n\n- `latest` - latest working version\n- `jessie-latest` - latest but will always remain on debian jessie\n- `hardened` - latest + [added security defaults](https://github.com/stilliard/docker-pure-ftpd/issues/10)\n\n**Previous version before tags were introduced**\n\n- `wheezy-1.0.36` - incase you want to roll back to before we started using debian jessie\n\n**Specific pure-ftpd versions**\n\n- `jessie-1.x.x` - jessie + specific versions, e.g. jessie-1.0.36\n- `hardened-1.x.x` - hardened + specific versions\n\n*Check the tags on github for available versions, feel free to submit issues and/or pull requests for newer versions*\n\nUsage of specific tags: \n`sudo docker pull stilliard/pure-ftpd:hardened-1.0.36`\n\n**An arm64 build is also available here:** https://hub.docker.com/r/zhabba/pure-ftpd-arm64 *- Thanks @zhabba*\n\n----------------------------------------\n\nOur default pure-ftpd options explained\n----------------------------------------\n\n```\n/usr/sbin/pure-ftpd # path to pure-ftpd executable\n-c 5 # --maxclientsnumber (no more than 5 people at once)\n-C 5 # --maxclientsperip (no more than 5 requests from the same ip)\n-l puredb:/etc/pure-ftpd/pureftpd.pdb # --login (login file for virtual users)\n-E # --noanonymous (only real users)\n-j # --createhomedir (auto create home directory if it doesnt already exist)\n-R # --nochmod (prevent usage of the CHMOD command)\n-P $PUBLICHOST # IP/Host setting for PASV support, passed in your the PUBLICHOST env var\n-p 30000:30009 # PASV port range (10 ports for 5 max clients)\n-tls 1 # Enables optional TLS support\n```\n\nFor more information please see `man pure-ftpd`, or visit: https://www.pureftpd.org/\n\nWhy so many ports opened?\n---------------------------\nThis is for PASV support, please see: [#5 PASV not fun :)](https://github.com/stilliard/docker-pure-ftpd/issues/5)\n\n----------------------------------------\n\nDocker Volumes\n--------------\nThere are a few spots onto which you can mount a docker volume to configure the\nserver and persist uploaded data. It's recommended to use them in production. \n\n  - `/home/ftpusers/` The ftp's data volume (by convention). \n  - `/etc/pure-ftpd/passwd` A directory containing the single `pureftpd.passwd`\n    file which contains the user database (i.e., all virtual users, their\n    passwords and their home directories). This is read on startup of the\n    container and updated by the `pure-pw useradd -f /etc/pure-\n    ftpd/passwd/pureftpd.passwd ...` command.\n  - `/etc/ssl/private/` A directory containing a single `pure-ftpd.pem` file\n    with the server's SSL certificates for TLS support. Optional TLS is\n    automatically enabled when the container finds this file on startup.\n\nKeep user database in a volume\n------------------------------\nYou may want to keep your user database through the successive image builds. It is possible with Docker volumes.\n\nCreate a named volume:\n```\ndocker volume create --name my-db-volume\n```\n\nSpecify it when running the container:\n```\ndocker run -d --name ftpd_server -p 21:21 -p 30000-30009:30000-30009 -e \"PUBLICHOST=localhost\" -v my-db-volume:/etc/pure-ftpd/passwd stilliard/pure-ftpd\n```\n\nWhen an user is added, you need to use the password file which is in the volume:\n```\npure-pw useradd bob -f /etc/pure-ftpd/passwd/pureftpd.passwd -m -u ftpuser -d /home/ftpusers/bob\n```\n(Thanks to the -m option, you don't need to call *pure-pw mkdb* with this syntax).\n\n\nChanging a password\n---------------------\ne.g. to change the password for user \"bob\":\n```\npure-pw passwd bob -f /etc/pure-ftpd/passwd/pureftpd.passwd -m\n```\n\n----------------------------------------\nDevelopment (via git clone)\n```bash\n# Clone the repo\ngit clone https://github.com/stilliard/docker-pure-ftpd.git\ncd docker-pure-ftpd\n# Build the image\nmake build\n# Run container in background:\nmake run\n# enter a bash shell inside the container:\nmake enter\n# test that it's all working with\nmake test\n```\n\nTLS\n----\n\nIf you want to enable tls (for ftps connections), you need to have a valid\ncertificate. You can get one from one of the certificate authorities that you'll\nfind when googling this topic. The certificate (containing private key and\ncertificate) needs to be at:\n\n```\n/etc/ssl/private/pure-ftpd.pem\n```\n\nUse docker volumes to get the certificate there at runtime. The container will\nautomatically enable optional TLS when it detect the file at this location.\n\nYou can also self-sign a certificate, which is certainly the easiest way to\nstart out. Self signed certificates come with certain drawbacks, but it might\nbe better to have a self signed one than none at all.\n\nHere's how to create a self-signed certificate from within the container:\n\n```bash\nmkdir -p /etc/ssl/private\nopenssl dhparam -out /etc/ssl/private/pure-ftpd-dhparams.pem 2048\nopenssl req -x509 -nodes -newkey rsa:2048 -sha256 -keyout \\\n    /etc/ssl/private/pure-ftpd.pem \\\n    -out /etc/ssl/private/pure-ftpd.pem\nchmod 600 /etc/ssl/private/*.pem\n```\n\nAutomatic TLS certificate generation\n------------------------------\n\nIf `ADDED_FLAGS` contains `--tls` (e.g. --tls=1 or --tls=2) and file `/etc/ssl/private/pure-ftpd.pem` does not exists\nit is possible to generate self-signed certificate if `TLS_CN`, `TLS_ORG` and `TLS_C` are set.\n\nKeep in mind that if no volume is set for `/etc/ssl/private/` directory generated\ncertificates won't be persisted and new ones will be generated on each start.\n\nYou can also pass `-e \"TLS_USE_DSAPRAM=true\"` for faster generated certificates\nthough this option is not recommended for production.\n\nPlease check out the [TLS docs here](https://download.pureftpd.org/pub/pure-ftpd/doc/README.TLS).\n\nTLS with cert and key file for Let's Encrypt\n------------------------------\n\nLet's Encrypt provides two separate files for certificate and keyfile. The [Pure-FTPd TLS encryption](https://download.pureftpd.org/pub/pure-ftpd/doc/README.TLS) documentation suggests to simply concat them into one file. \nSo you can simply provide the Let's Encrypt cert ``/etc/ssl/private/pure-ftpd-cert.pem`` and key ``/etc/ssl/private/pure-ftpd-key.pem`` via Docker Volumes and let them get auto-concatenated into ``/etc/ssl/private/pure-ftpd.pem``.\nOr concat them manually with\n```sh\ncat /etc/letsencrypt/live/\u003cyour_server\u003e/cert.pem /etc/letsencrypt/live/\u003cyour_server\u003e/privkey.pem \u003e pure-ftpd.pem\n```\n\n\nCredits\n-------------\nThanks for the help on stackoverflow with this!\nhttps://stackoverflow.com/questions/23930167/installing-pure-ftpd-in-docker-debian-wheezy-error-421\n\nAlso thanks to all the awesome contributors that have made this project amazing!\nhttps://github.com/stilliard/docker-pure-ftpd/graphs/contributors\n\nYou can also help support the development of this project with coffee power:\n\u003ca href=\"https://www.buymeacoffee.com/stilliard\" target=\"_blank\"\u003e\u003cimg src=\"https://cdn.buymeacoffee.com/buttons/default-orange.png\" alt=\"Buy Me A Coffee\" style=\"height: 51px !important;width: 217px !important;\" \u003e\u003c/a\u003e\n\n## License\n[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fstilliard%2Fdocker-pure-ftpd.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2Fstilliard%2Fdocker-pure-ftpd?ref=badge_large)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstilliard%2Fdocker-pure-ftpd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstilliard%2Fdocker-pure-ftpd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstilliard%2Fdocker-pure-ftpd/lists"}