Cotton is a self-hosted file cloud, so installing it is less about memorizing commands and more about understanding the small set of pieces that must stay healthy: the app, the database, the file storage, the domain, HTTPS, and backups.
Cotton is the application people open in the browser. PostgreSQL stores the file tree, accounts, shares, settings, and metadata. The real file bytes live in Cotton's chunk storage on a filesystem path or an S3-compatible backend.
A clean install starts with choosing where Cotton will live and how people will reach it. The same idea works on a home server, mini PC, NAS-like box, or VPS, but public installs need more discipline around HTTPS and backups.
Docker is the packaging and launch format. Instead of installing runtime pieces by hand on the host, Docker starts Cotton from an image with the expected application environment. Compose is the recipe that says which containers run together and which folders survive restarts.
For testing, a local machine is fine. For real use, pick a host that can stay online and be backed up. A laptop that sleeps is a bad server; a small home server or VPS is usually a better starting point.
Cotton can store chunks on a filesystem path or use S3-compatible storage. Filesystem storage is the simplest path when the server owns the disk. S3-compatible storage is useful when capacity, durability, or separate storage operations matter more.
If Cotton is public, put it behind a reverse proxy and serve it over HTTPS. DNS points a name to the server, the reverse proxy receives web traffic, and TLS keeps browser traffic encrypted in transit.
After the containers are running, Cotton's setup wizard handles the product decisions: admin account, storage choice, email mode, timezone, telemetry preference, and key mode. That keeps the first install understandable instead of hiding everything in environment variables.
The install is not finished just because the login page loads. Enable strong admin authentication, check the admin security diagnostics, confirm backups, and make sure you know how to update the containers without losing the database or chunk storage.
A good Cotton install leaves you with a reachable HTTPS site, a known PostgreSQL database, a known persistent chunk store, an admin account protected by stronger auth, a backup path, and a clear update routine.
The practical goal is not to make Docker print a success line. The goal is a file cloud you can reach, update, back up, secure, and explain later when something has to move or be restored.
Do not skip backups, key custody, HTTPS, or persistent storage just because the first container start worked. Those are not advanced extras; they are the line between a demo and a file cloud you can trust.
The page above explains the moving parts. This is the actual order of operations: prepare the host, start two containers, finish setup in the browser, then lock it down. Roughly fifteen minutes on a server you already have.
Four things that have to be in place before any of the steps make sense.
A home server, mini PC, NAS-like box, or VPS with enough disk for the files you expect.
Docker Engine with the Compose plugin. Everything below runs as two containers.
A directory like /data/cotton that survives restarts. It holds chunks and the encrypted key sentinel.
For access from the internet, a domain plus a reverse proxy that terminates HTTPS. Local-only installs can skip this at first.
Each step is short. Keep the order: data, containers, browser, then defense.
Install Docker and the Compose plugin, then create the storage directory: mkdir -p /data/cotton. This is where Cotton keeps file chunks.
Create one strong secret and reuse it for Postgres and Cotton. Do not leave a default password on an exposed instance.
Paste the compose below, replace the password placeholders, and save it next to your storage path.
Run docker compose up -d, then watch the logs until Cotton reports it is listening on port 8080.
Open the instance and complete the setup wizard: admin account, storage, email, timezone, telemetry, and key mode.
For public access, route your domain through the reverse proxy on 80/443, then run the post-install checklist.
This is the same compose shape from the deployment page. Replace both password placeholders with the secret you generated, keep /data/cotton durable, and put TLS at your reverse proxy.
services:
postgres:
image: postgres:18
restart: always
environment:
POSTGRES_DB: cotton
POSTGRES_USER: cotton
POSTGRES_PASSWORD: "replace with output of: openssl rand -base64 32"
cotton:
image: bvdcode/cotton:latest
restart: always
depends_on:
- postgres
ports:
- "8080:8080"
volumes:
- /data/cotton:/app/files
environment:
COTTON_PG_HOST: postgres
COTTON_PG_PORT: "5432"
COTTON_PG_DATABASE: cotton
COTTON_PG_USERNAME: cotton
COTTON_PG_PASSWORD: "same value as POSTGRES_PASSWORD"
COTTON_RESTORE_DATABASE_IF_EMPTY: "true"
# Optional unattended restarts; otherwise unlock in browser:
# COTTON_MASTER_KEY: "replace with output of: openssl rand -base64 24"
security_opt:
- no-new-privileges:trueFrom an empty directory to first-run logs. Run them on the host where Cotton will live.
# 1. create the storage directory mkdir -p /data/cotton # 2. generate one strong database password openssl rand -base64 32 # 3. start Postgres and Cotton docker compose up -d # 4. follow first-run logs docker compose logs -f cotton
Product decisions live in the UI instead of hidden environment folklore.
Create the first administrator. This account owns the instance, so protect it immediately after.
Filesystem path or S3-compatible backend for file chunks. Filesystem is the simplest first install.
Cloud Cotton Mail, your own SMTP, or email disabled. Public instances usually want working email.
Set the instance timezone so timestamps, schedules, and logs read correctly.
Set your telemetry preference. Cotton's telemetry is opt-in, so you decide during setup.
Browser unlock keeps the master key out of the container, or set COTTON_MASTER_KEY for unattended restarts. Pick the tradeoff that fits.
The login page loading is not the finish line.
Enable passkeys or TOTP for the admin account before the instance is reachable from outside.
The admin checkup flags public signup, missing 2FA, writable rootfs, Docker socket exposure, and more.
Verify Postgres and chunk-storage backups land somewhere other than the same server.
Confirm how you pull a new image and restart without losing the database or chunk storage.
You do not need to be a Docker expert, but you should understand three things: containers run the app, volumes keep data across restarts, and deleting the wrong volume can delete real data.
Yes. A home server, mini PC, or NAS-like machine can work well when it stays online, has enough storage, and has a backup plan. Public access still needs HTTPS and a reverse proxy.
For local-only testing, no. For a public instance, use a domain and HTTPS so browsers, mobile clients, and desktop clients have one stable secure address.
PostgreSQL stores structured metadata: accounts, folders, file records, shares, settings, and operational state. The large file content is stored separately as Cotton chunks.
Cotton stores file content as chunks in the configured storage backend. That backend can be a persistent filesystem path or S3-compatible storage.