Deploying asciinema

Introduction

asciinema is an open-source solution for recording and sharing terminal sessions. Unlike traditional screen recording tools, asciinema captures terminal output as text, resulting in small file sizes, crisp playback at any resolution, and the ability to copy-paste from recordings.

The asciinema server component allows you to host your own instance where users can upload, manage, and share their terminal recordings. This self-hosted approach gives you full control over your recordings and provides a private platform for teams to share terminal sessions.

Key highlights of asciinema:

Lightweight Recordings: Text-based format produces tiny files compared to video
Perfect Quality: No compression artifacts, always crisp at any zoom level
Copy-Paste Support: Viewers can copy text directly from recordings
Embeddable Player: Include recordings in documentation and blog posts
Terminal Themes: Multiple color themes for playback
Speed Control: Adjust playback speed during viewing
Seeking: Jump to any point in the recording
API Access: Programmatic upload and management
User Accounts: Multi-user support with personal recording libraries
Private Recordings: Control visibility of your recordings
SVG/GIF Export: Convert recordings to shareable formats

This guide walks through deploying your own asciinema server on Klutch.sh using Docker.

Why Deploy asciinema on Klutch.sh

Deploying asciinema on Klutch.sh provides several advantages for terminal recording:

Privacy Control: Keep sensitive terminal sessions private on your own infrastructure.

Team Collaboration: Share recordings internally without public visibility.

HTTPS by Default: Secure upload and playback with automatic SSL certificates.

Persistent Storage: Reliable storage for all your terminal recordings.

Custom Branding: Use your own domain for a professional recording platform.

GitHub Integration: Deploy updates automatically when you push changes.

Prerequisites

Before deploying asciinema on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your configuration
Basic understanding of Docker and containerization
The asciinema CLI installed locally for recording
(Optional) A custom domain for your asciinema instance

Understanding asciinema Architecture

asciinema consists of several components:

asciinema CLI: Command-line tool for recording terminal sessions.

asciinema Server: Web application for hosting and playing recordings.

asciinema Player: JavaScript player for embedding recordings.

PostgreSQL Database: Stores user accounts and recording metadata.

File Storage: Stores the actual recording files (asciicast format).

Preparing Your Repository

Create a GitHub repository for your asciinema server deployment.

Repository Structure

asciinema-deploy/
├── Dockerfile
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile for asciinema server:

FROM ghcr.io/asciinema/asciinema-server:latest

# Environment variables
ENV DATABASE_URL=${DATABASE_URL}
ENV SECRET_KEY_BASE=${SECRET_KEY_BASE}
ENV URL_SCHEME=https
ENV URL_HOST=${URL_HOST}
ENV URL_PORT=443

# SMTP configuration (optional)
ENV SMTP_HOST=${SMTP_HOST}
ENV SMTP_PORT=${SMTP_PORT:-587}
ENV SMTP_USERNAME=${SMTP_USERNAME}
ENV SMTP_PASSWORD=${SMTP_PASSWORD}
ENV SMTP_FROM_ADDRESS=${SMTP_FROM_ADDRESS}

# Expose port
EXPOSE 4000

# Start the server
CMD ["./bin/asciinema", "start"]

Environment Variables Reference

Variable	Required	Default	Description
`DATABASE_URL`	Yes	-	PostgreSQL connection string
`SECRET_KEY_BASE`	Yes	-	Secret key for encryption (64+ hex characters)
`URL_HOST`	Yes	-	Hostname for your server
`URL_SCHEME`	No	https	URL scheme (http/https)
`URL_PORT`	No	443	Port for URL generation
`SMTP_HOST`	No	-	SMTP server for email
`SMTP_PORT`	No	587	SMTP port
`SMTP_USERNAME`	No	-	SMTP username
`SMTP_PASSWORD`	No	-	SMTP password

Deploying asciinema on Klutch.sh

Generate Secret Key

Create a secure secret key:

openssl rand -hex 64

Save this key for configuration.

Push Your Repository to GitHub

Initialize and push your configuration to GitHub.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project named “asciinema” or “terminal-recordings”.

Create a New App

Within your project, create a new app and connect your GitHub repository.

Configure HTTP Traffic

Set up HTTP for the web interface:

Select HTTP as the traffic type
Set the internal port to 4000

Set Environment Variables

Configure the following:

Variable	Value
`DATABASE_URL`	PostgreSQL connection string
`SECRET_KEY_BASE`	Your generated 64+ character hex key
`URL_HOST`	your-app-name.klutch.sh

Attach Persistent Volumes

Add storage for recordings:

Mount Path	Recommended Size	Purpose
`/app/uploads`	20 GB	Terminal recording files
`/app/tmp`	1 GB	Temporary files

Deploy Your Application

Click Deploy to build and start asciinema server.

Access Your Instance

Once deployment completes, access your server at https://your-app-name.klutch.sh.

Initial Configuration

Creating an Account

Navigate to your asciinema server
Click “Sign up” or “Log in”
If email is configured, use email login
Otherwise, use the install ID from the CLI

Connecting the CLI

Configure the asciinema CLI to use your server:

Install asciinema CLI locally
Configure your server URL:
Terminal window
```
asciinema auth
```
Follow the authentication URL
Confirm the connection

Recording Terminal Sessions

Basic Recording

Start a recording:

asciinema rec demo.cast

End the recording with exit or Ctrl+D.

Uploading Recordings

Upload to your server:

asciinema upload demo.cast

The recording URL is displayed after upload.

Recording Options

Customize your recordings:

# Set custom title
asciinema rec -t "My Demo" demo.cast

# Set idle time limit
asciinema rec --idle-time-limit 2 demo.cast

# Record specific command
asciinema rec -c "htop" htop.cast

Managing Recordings

Web Interface

The web interface provides:

List of all your recordings
Playback with speed controls
Sharing and embed options
Privacy settings
Recording metadata editing

Privacy Settings

Control recording visibility:

Public: Anyone with the URL can view
Unlisted: Only visible to those with the link
Private: Only visible when logged in

Embedding Recordings

Get embed code for your recordings:

<script
  id="asciicast-123456"
  src="https://your-server.com/a/123456.js"
  async>
</script>

asciinema Player

Self-Hosted Player

For custom integrations, use the standalone player:

<div id="player"></div>
<script src="https://your-server.com/js/player.js"></script>
<script>
  AsciinemaPlayer.create(
    '/recordings/demo.cast',
    document.getElementById('player'),
    { theme: 'monokai' }
  );
</script>

Player Options

Customize playback:

theme: Color theme (asciinema, monokai, etc.)
speed: Playback speed multiplier
idleTimeLimit: Maximum idle time
poster: Preview frame to show
autoPlay: Start playing automatically

Troubleshooting Common Issues

Upload Failed

Solutions:

Verify CLI is configured with correct server URL
Check authentication is completed
Review server logs for errors

Recording Not Playing

Solutions:

Verify recording file is valid asciicast format
Check browser console for errors
Try different browser or incognito mode

Email Not Sending

Solutions:

Verify SMTP settings are correct
Check SMTP credentials
Review server logs for email errors

Additional Resources

Conclusion

Deploying asciinema on Klutch.sh gives you a private, self-hosted platform for recording and sharing terminal sessions. Whether for documentation, tutorials, or team collaboration, asciinema provides an elegant solution for capturing terminal workflows with the benefits of text-based recordings.