# Install with Docker

Run Mailpiece as one ready-made container. There's nothing to build on the server.

Paste this into your agent:

> Install Mailpiece on my server with Docker. Read mailpiece.dev/llms.txt first.

## What you need

The image is `ghcr.io/mailpiece/mailpiece:main`, built from `main` on each change, with web and jobs together. The server needs Docker and what [What you need](https://mailpiece.dev/docs/install.html#what-you-need) lists there.

To change the code and deploy it from your computer, [install with Kamal](https://mailpiece.dev/docs/install) instead.

## Make the secret key

Make it once and keep it safe apart from the server: the relay token and SMTP password Mailpiece stores are encrypted with keys derived from it. A new one also signs everyone out, and the rating links in issues already mailed stop answering.

```sh
openssl rand -hex 64      # SECRET_KEY_BASE
```

## Run it

Mount a named volume at `/rails/storage`, or the databases, uploads and certificate are lost with the container. One container runs web and jobs; the database is created on first start. The settings are explained in [Configuration](https://mailpiece.dev/docs/configuration).

Then open `/signup` and create the first account, as in [Open it](https://mailpiece.dev/docs/install.html#open-it).

```sh
docker run -d --name mailpiece --restart unless-stopped \
  --publish 80:80 --publish 443:443 \
  --volume mailpiece:/rails/storage \
  --env SECRET_KEY_BASE=... \
  --env TLS_DOMAIN=app.example.com \
  --env BASE_URL=https://app.example.com \
  --env "MAILER_FROM_ADDRESS=My Newsletter <hello@example.com>" \
  --env SMTP_ADDRESS=smtp.example.com \
  --env SMTP_USERNAME=... \
  --env SMTP_PASSWORD=... \
  ghcr.io/mailpiece/mailpiece:main
```

## With docker compose

The same container. Start it with `docker compose up -d`.

```sh
services:
  web:
    image: ghcr.io/mailpiece/mailpiece:main
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    environment:
      - SECRET_KEY_BASE=...
      - TLS_DOMAIN=app.example.com
      - BASE_URL=https://app.example.com
      - MAILER_FROM_ADDRESS=My Newsletter <hello@example.com>
      - SMTP_ADDRESS=smtp.example.com
      - SMTP_USERNAME=...
      - SMTP_PASSWORD=...
    volumes:
      - mailpiece:/rails/storage

volumes:
  mailpiece:
```

## Update it

Mailpiece stops while the new container boots.

```sh
docker pull ghcr.io/mailpiece/mailpiece:main
docker stop mailpiece && docker rm mailpiece
# then the same docker run as above

# Under compose
docker compose pull && docker compose up -d
```

## On a laptop

Leave `TLS_DOMAIN` out, publish port `80` only and set `DISABLE_SSL=true` to reach Mailpiece over plain HTTP. Plain HTTP is for trying Mailpiece on your own machine.

Behind a proxy that handles HTTPS, leave `TLS_DOMAIN` out and publish port `80` only, without `DISABLE_SSL`.

```sh
# On a laptop
docker run ... --publish 80:80 --env DISABLE_SSL=true --env BASE_URL=http://localhost ...

# Behind a proxy that handles HTTPS
docker run ... --publish 80:80 ...
```

## Then

Take your [first steps](https://mailpiece.dev/docs/first-steps).

Still need help? Ask on [GitHub](https://github.com/mailpiece/mailpiece).