For administrators
← All topics

Installing, step by step

The complete guide: downloading and checking the bundle, ./draften install, HTTPS, the licence, mail and securing the server.

The whole procedure from an empty server to secure operation: downloading the bundle, installation, HTTPS, the first sign-in, settings and securing the server. What the server must meet is in Supported environment; what an installation is made of is described in Installing on your own server.

Before you start

Have ready:

Step 1: Prepare the server

Install Docker Engine with the compose plugin. On Ubuntu, from Docker's official repository:

sudo apt-get update
sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

On other distributions, follow https://docs.docker.com/engine/install/. The docker.io package from the distribution's repositories tends to be old and has no compose plugin.

Check the versions — Docker must be 24 or newer and docker compose must answer:

docker version --format '{{.Server.Version}}'
docker compose version

Step 2: Download the bundle

The bundle is downloaded from download.draften.ai with the key inside the licence file. These commands take the key out of the licence and list the available releases:

KEY=$(sed -n 's/.*"payload":"\([^"]*\)".*/\1/p' licence-<number>.json | tr '_-' '/+' | awk '{ while (length($0) % 4) $0 = $0 "="; print }' | base64 -d | sed -n 's/.*"key": *"\([^"]*\)".*/\1/p')
curl -fsS -H "Authorization: Bearer $KEY" https://download.draften.ai/v1/latest.json | sed -n 's/.*"payload":"\([^"]*\)".*/\1/p' | tr '_-' '/+' | awk '{ while (length($0) % 4) $0 = $0 "="; print }' | base64 -d

The listing shows the releases of the last six months — for each the version, date, notes, size and sha256 checksum — and, under latest, the newest one that has not been withdrawn. Download that version:

curl -fS -H "Authorization: Bearer $KEY" -o draften-<version>.tar https://download.draften.ai/v1/bundles/draften-<version>.tar

The bundle is about 500 MB. When the gateway answers with error 403, the licence is unknown, revoked or expired — the message says which.

A server without internet: download the bundle on another machine with the same commands and carry it over to the server (with scp, say). In that case we can also send you the checksum with the bundle.

Step 3: Check the bundle

Compute the checksum and compare it with the sha256 value of that version in the listing from step 2:

sha256sum draften-<version>.tar

If the checksums differ, do not install the bundle and get in touch with us. This is the only manual check: every later update the installation checks by itself against our keys.

Step 4: Unpack the bundle and run the installer

Choose the directory the installation will live in, unpack the bundle into it and run the installer:

sudo mkdir /srv/draften
sudo tar -xf draften-<version>.tar -C /srv/draften
cd /srv/draften
sudo ./draften install

The installer first loads the images (a minute or two) and checks the signature and the contents of the bundle. If the check fails ("this bundle does not check out"), the bundle is damaged — download it again.

Step 5: Answer the installer's questions

The installer asks in English:

QuestionWhat to enter
Where will people open draften (the full address)the address including https://, such as https://draften.firma.cz. It must be the address people really use — the redirect addresses for signing in with Microsoft and Google are built from it too
The organisation's nameyour organisation's name
Its short namea short name: lowercase letters, digits and hyphens. It suggests one from the organisation's name
The first administrator's e-mailthe first administrator's e-mail. They become the organisation's owner and the operator of the whole installation
Their nametheir name
Their languagecs, en, de, fr, es, it, pt or pl (default en)
Run the updateryes or no (default yes). The updater lets you update, change the number of processes, replace the encryption key and make backups from the web interface. It has access to Docker, which means root rights on the server. Without it, everything works from the command line
HTTPS certificate file (PEM)the path to the certificate, if HTTPS is to end right in draften; otherwise leave it empty
Its private key filethe path to the certificate's key

With a certificate, the address must start with https://. Every answer can also be given right in the command, so you can script the installation; ./draften help lists the options:

sudo ./draften install --url https://draften.firma.cz --org "Firma Ltd" \
  --admin-email jan@firma.cz --admin-name "Jan Novák" --locale en --updater yes

Step 6: What the installer does

  1. It writes the settings and secrets into the .env file — readable only by its owner. It generates the database passwords, the MASTER_KEY encryption key and the session secret at random and prints them nowhere.
  2. It creates the data/ and backups/ folders and the first organisation with its administrator.
  3. It starts draften and checks that it answers.
  4. At the end it prints the address and the link for setting the first administrator's password, and reminds you to keep a copy of .env.

If the first start fails ("the first start failed"), look at docker compose ps and docker compose logs. If it does not print the link, you find it with docker compose logs worker | grep set-password — the worker prints it at every start until the password exists.

Keep a copy of .env off the server straight away — at least the MASTER_KEY value. This key encrypts the mailbox access, the model keys and the passwords for sending mail. Without it nobody can read them, not even from a backup — and we do not have it.

Step 7: Publish draften over HTTPS

Choose one option depending on where HTTPS ends. Point the DNS record for your address at the server (or at the proxy).

HTTPS right in draften

When you gave the installer a certificate, draften listens on port 443 and redirects from port 80 to HTTPS. DNS and open ports 80 and 443 are all it takes. A certificate can also be added later, and after a renewal you replace it with the same command without losing a single request:

sudo ./draften certificate cert.pem key.pem --url https://draften.firma.cz

You take care of renewing the certificate yourself (with an ACME client, say); run this command after every renewal.

Your reverse proxy

Without a certificate, draften listens only on 127.0.0.1:8085. A proxy on the same machine sends the requests to this address and passes on the Host and X-Forwarded-Proto headers. For example for Caddy (it obtains the certificate by itself):

draften.firma.cz {
    reverse_proxy 127.0.0.1:8085
}

or for nginx:

server {
    listen 443 ssl;
    server_name draften.firma.cz;
    ssl_certificate     /etc/ssl/draften/fullchain.pem;
    ssl_certificate_key /etc/ssl/draften/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8085;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

When the proxy runs on another machine, set WEB_BIND=0.0.0.0:8085 in .env, run sudo docker compose up -d and open port 8085 to the proxy only (see step 13).

Cloudflare Tunnel

It needs no open port. In Cloudflare Zero Trust, create a tunnel and copy its token. Put CLOUDFLARE_TUNNEL_TOKEN=<token> into .env, add tunnel to COMPOSE_PROFILES (say COMPOSE_PROFILES=updater,tunnel) and run:

sudo docker compose up -d

Then, in Cloudflare, add a public address (Public hostname) to the tunnel leading to http://127.0.0.1:8085. Leave WEB_BIND at 127.0.0.1:8085. Docker downloads the cloudflared image from Docker Hub — it is not in the bundle.

Step 8: Set your password and sign in

Open the link the installer printed, set the password and you are signed in. The link works once and is valid for 7 days. What the password page looks like is shown in the guide Signing in.

Do not copy the link anywhere or forward it — whoever has it sets the administrator's password.

Step 9: Upload the licence

In the interface, open Installation → Installation, choose the file in the Licence card at the bottom and upload it. Until the installation has a licence, the assistants process no mail and no mailbox or assistant can be created. With a licence, the updater watches for new releases by itself. More in The licence.

Step 10: Set the default keys and outgoing mail

On the same Installation page:

Step 11: Connect mail and people

  1. Decide how the assistant will get to the mail, and prepare it at Microsoft or Google: Microsoft 365, Google Workspace, other mailboxes over IMAP.
  2. Who is to sign in with a Microsoft or Google account, you set in How members sign in.
  3. Add and connect a mailbox.
  4. Set up an assistant with the wizard.
  5. Invite more people — People and roles.

Step 12: Check that everything runs

sudo ./draften status

prints the version, the health of the web and the workers, the HTTPS status and the backups. In the interface, the Operations page shows whether the workers check in — see Operations and capacity. When something does not work, Troubleshooting helps; sudo ./draften diagnose creates a file for our support.

Step 13: Secure the server

Whoever has access to the server has access to everything: to the mail in the messages, to .env with the key and to the backups. So protect the server as you would a mail server.

Firewall. From outside, let in only what is needed:

Docker bypasses UFW rules (and firewalld) for the ports it publishes. ufw deny 8085 does not close a port Docker opened on 0.0.0.0. So leave WEB_BIND at 127.0.0.1:8085 where you can; where you cannot, restrict access with a firewall in front of the server or with rules in the DOCKER-USER chain.

Outgoing connections only need to be allowed to the addresses in Supported environment.

SSH. Sign-in with a key only (PasswordAuthentication no), no direct root sign-in (PermitRootLogin no), administrators with their own accounts and sudo.

Who may use Docker. Membership in the docker group means root rights. Give it only to the server's administrators.

System updates. Switch on automatic security updates (on Ubuntu, unattended-upgrades) and update Docker along with the system. draften's updates are taken care of by the updater — see Updating with the updater.

The updater. It has access to Docker, which means root rights. If you do not need it, switch it off: remove updater from COMPOSE_PROFILES in .env and run sudo docker compose rm -sf updater in the installation directory. You then do updates and backups from the command line.

The installation's files. .env is readable only by its owner, and so is the backups/ folder — keep it that way. Do not share the installation directory.

Backups off the server. draften backs up the database every day into backups/ on the same disk. Set up copying backups/ and .env somewhere else, encrypted — the dumps contain mail. Details: Backup and restore.

The encryption key. When someone who knew .env leaves, replace MASTER_KEY (sudo ./draften rotate-key, or under Installation) and keep the new copy of .env off the server.

Next

Plain text version