asciinema.org/docs/INSTALL.md

asciinema web app install guide

The only officially supported installation procedure of asciinema web app is Docker based. You must have SSH access to a 64-bit Linux server with Docker support.

If you really, really want to install everything manually then look at Dockerfile and docker-compose.yml to see what's required by the app.

Hmm, why Docker?

Hosting non-trivial web applications is complicated. Setting this one up requires installation of fair number of system packages and build tools, configuring monitoring of several processes, as well as configuring Nginx. Also, you need PostgreSQL, Redis, and SMTP server.

With Docker, you get the battle tested configuration (similar to what's running on asciinema.org), in a stable container, along with all required services preconfigured.

It also makes upgrading to new versions much easier.

Hardware Requirements

• modern single core CPU, dual core recommended
• 1 GB RAM minimum (with swap)
• 64 bit Linux compatible with Docker
• 10 GB disk space minimum

Service Requirements

asciinema web app requires the following services:

• Postgres 9.5+
• Redis 2.6+
• SMTP server

If you go with the provided docker-compose.yml file you don't need to worry about these - they're included and already configured to work with this app.

Installation

This guide assumes you already have Docker engine and docker-compose running on the installation host.

You don't have to use docker-compose to use asciinema web app Docker image. Feel free to inspect docker-compose.yml file and run required services manually with docker run .... However, for the sake of simplicity and to miminize configuration issues the rest of this guide is based on the provided/suggested docker-compose configuration.

Clone the repository

git clone --recursive https://github.com/asciinema/asciinema.org.git

It's recommended to checkout a new branch, to keep any customizations separate from master branch and make upgrading safer:

git checkout -b example

Edit config file

You need to create .env.production config file. The easiest is to use provided .env.production.sample as a template:

cp .env.production.sample .env.production
nano .env.production

There are several variables which have to be set, like BASE_URL and SECRET_KEY_BASE. The rest is optional, and most likely used when you want to use your own SMTP, PostgreSQL or Redis server.

Basic settings

Set BASE_URL to the URL your users are supposed to reach this instance at. Example: http://asciinema.example.com.

Set SECRET_KEY_BASE to long random string. Run docker-compose run --rm web bundle exec rake secret to obtain one.

SMTP settings

The app uses linked namshi/smtp container, which by default runs in "SMTP Server" mode. Set MAILNAME to the outgoing mail hostname, for example, use the same hostname as in BASE_URL.

You can configure it to act as GMail relay, Amazon SES relay or generic SMTP relay. See namshi/docker-smtp README for details.

For example, to send emails through GMail add GMAIL_USER and GMAIL_PASSWORD (most likely App Password) variables to the config file.

Database settings

DATABASE_URL and REDIS_URL point to linked postgres and redis containers by default. You can set these so they point to your existing services. Look at "Service Requirements" above for minimum versions supported.

Specify volume mappings

The container has two volumes, for user uploads and for application logs. The default docker-compose.yml maps them to the repository's uploads and log directories, you may wish to put them somewhere else.

Likewise, the PostgreSQL and Redis images have data volumes that you may wish to map somewhere where you know how to find them and back them up. By default they're mapped inside repository's volumes directory.

Initialize the database

You have the config file ready and the data volumes mapped. It's time to set up the database.

Start PostgreSQL container (skip this if you use existing PostgreSQL server):

docker-compose up -d postgres

Create database schema and seed it with initial data:

docker-compose run --rm web setup

Create containers

The final step is to create the containers:

docker-compose up -d

Check the status of newly created containers:

docker ps -f 'name=asciinema_'

You should see asciinema_web, asciinema_postgres and a few others listed.

Point your browser to BASE_URL and enjoy your own asciinema hosting site!

Upgrading

Stop all containers:

docker-compose stop

Pull latest code from upstream and merge it into your branch:

git fetch origin
git merge origin/master

Upgrade database:

docker-compose run --rm web upgrade

Start new containers:

docker-compose up -d

Using asciinema recorder with your instance

Once you have your instance running, point asciinema recorder to it by setting API URL in ~/.config/asciinema/config file as follows:

[api]
url = https://your.asciinema.host

Alternatively, you can set ASCIINEMA_API_URL environment variable:

ASCIINEMA_API_URL=https://your.asciinema.host asciinema rec