Skip to content

Quick start

This guide shows how to setup your own instance of asciinema server for hosting terminal session recordings.

For a broader overview of what's possible with asciinema check out the intro guide.

Tip

Running NixOS? Use the NixOS module instead of docker-compose.

To keep this guide simple we'll use the official asciinema server container image, ghcr.io/asciinema/asciinema-server, in a docker-compose based setup. If you prefer to use a different deployment solution it should be straightforward to adapt the configuration presented below to specifics of your environment.

Here's a basic docker-compose configuration for asciinema server you can use as a template.

docker-compose.yml
services:
  asciinema:
    image: ghcr.io/asciinema/asciinema-server:20251114
    environment:
      - SECRET_KEY_BASE=  # <- see below
      - URL_HOST=asciinema.example.com
      - URL_SCHEME=https
      - SMTP_HOST=smtp.example.com
      - SMTP_USERNAME=foobar
      - SMTP_PASSWORD=hunter2
    volumes:
      - asciinema_data:/var/lib/asciinema
    depends_on:
      postgres:
        condition: service_healthy

  postgres:
    image: docker.io/library/postgres:14
    environment:
      - POSTGRES_HOST_AUTH_METHOD=trust
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres']
      interval: 2s
      timeout: 5s
      retries: 10

  caddy:
    image: caddy:2
    command: caddy reverse-proxy --from https://asciinema.example.com --to http://asciinema:4000
    ports:
      - '80:80'
      - '443:443'
      - '443:443/udp'
    volumes:
      - caddy_data:/data
      - caddy_config:/config

volumes:
  asciinema_data:
  postgres_data:
  caddy_data:
  caddy_config:
docker-compose.yml
services:
  asciinema:
    image: ghcr.io/asciinema/asciinema-server:20251114
    ports:
      - '80:4000'
    environment:
      - SECRET_KEY_BASE=  # <- see below
      - URL_HOST=asciinema.example.com
      - URL_PORT=80
      - SMTP_HOST=smtp.example.com
      - SMTP_USERNAME=foobar
      - SMTP_PASSWORD=hunter2
    volumes:
      - asciinema_data:/var/lib/asciinema
    depends_on:
      postgres:
        condition: service_healthy

  postgres:
    image: docker.io/library/postgres:14
    environment:
      - POSTGRES_HOST_AUTH_METHOD=trust
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres']
      interval: 2s
      timeout: 5s
      retries: 10

volumes:
  asciinema_data:
  postgres_data:

Let's break it down.

The asciinema container uses a server image version tagged 20251114. This is merely an example; please check the releases page for the latest stable version number and use that instead.

The SECRET_KEY_BASE environment variable is used for encryption/signing of user sessions (amongst other things). You can generate one with the following command:

tr -dc A-Za-z0-9 </dev/urandom | head -c 64; echo

The URL_SCHEME, URL_HOST and URL_PORT variables configure the root URL used for link generation. The URL_HOST should match the DNS name by which the server is accessible.

Check general configuration for more information on SECRET_KEY_BASE and URL_* variables.

The SMTP_* variables configure the SMTP server used for sending short-lived login links. They're optional: if you don't set them no mail is sent, and you log in via a link from the server logs instead (see below). Check email configuration for more details, including configuration examples for popular SMTP providers.

The server stores the uploaded recordings and other data at /var/lib/asciinema. We used volume mapping for this directory, but you can also bind-mount it to a directory on the host system, e.g. /path/to/asciinema/data:/var/lib/asciinema, or use S3-compatible object store instead. Check file store configuration for details.

The server utilizes PostgreSQL as its database; therefore we have included a dedicated postgres service, mapping its data directory, /var/lib/postgresql/data, to a volume. For convenience, asciinema server container image sets DATABASE_URL to postgresql://postgres@postgres/postgres, enabling it to connect to the postgres container automatically. Check the database configuration for more information on DATABASE_URL, including the use of a separate/external PostgreSQL server.

Finally, the caddy service runs Caddy web server in reverse proxy mode, with automatic HTTPS enabled for the domain specified with the --from argument (which should be the same as the URL_HOST on asciinema service). See HTTPS configuration for additional information.

Assuming you have set SECRET_KEY_BASE and URL_* variables, and opened ports 80 and 443 in the host system's firewall, you can now launch the stack with:

docker compose up

You will see PostgreSQL perform its initial setup, asciinema server create its database tables, and Caddy attempt to obtain a TLS certificate for your domain. Visit the configured URL in your web browser to verify it's up and running.

Congratulations! You have your own asciinema server instance 🎉

With the server up, log in to create your account. Open your server's URL, click Sign in / Sign up, and enter your email address - asciinema uses passwordless login and issues a one-time sign-in link.

If you set the SMTP_* variables, the link arrives by email. If you didn't, the server writes it to its log instead; read the latest one and open it in your browser:

docker compose logs asciinema | grep 'url from email'

The first account to register becomes your instance's admin, so there's no separate setup step. Once you're in, you can close public sign-ups with SIGN_UP_DISABLED=true. See Email and Administration for more.

Now, point asciinema CLI to your server by setting ASCIINEMA_API_URL, and upload a recording:

export ASCIINEMA_SERVER_URL=https://asciinema.example.com
asciinema upload demo.cast

export ASCIINEMA_API_URL=https://asciinema.example.com
asciinema upload demo.cast

Check the CLI configuration section for information on how to set the server URL permanently via the configuration file.