Getting Started

Getting Started

Requirements

  • A Debian-based server (Debian 12/13, Ubuntu 22.04+) with root access
  • A domain name pointed at your server (recommended for SSL)
  • Ports 80 and 443 open (for nginx + SSL)

Installation

Run the installer

curl -fsSL https://raw.githubusercontent.com/Macro002/AnkiBase/main/install.sh | sudo bash

The installer will:

  • Install Node.js 20 and Python if not already present
  • Build the frontend
  • Find an available port (starting at 8000)
  • Generate a secret key and encryption config
  • Set up the systemd services (ankibase, and ankibase-anki for the Anki engine)
  • Optionally configure nginx reverse proxy + SSL via Certbot

Complete the setup wizard

On first visit, a setup wizard walks you through:

  1. Creating your admin account
  2. Creating your first profile (an Anki collection)
  3. Bringing your cards over: AnkiWeb, your own sync server, or a sync server AnkiBase runs for you
  4. An optional AI key for stories

Log in

Use the credentials you just created. The login page includes rate limiting — 5 failed attempts per username triggers a lockout.

Updating

In-app: An update button appears in the header when a new version is available. Click it to update automatically with zero downtime.

Via terminal:

curl -fsSL https://raw.githubusercontent.com/Macro002/AnkiBase/main/install.sh | sudo bash -s -- --update

Useful Commands

# Live logs
journalctl -u ankibase -f
 
# Restart the service
systemctl restart ankibase
 
# Check status
systemctl status ankibase

The Anki engine

Anki runs as one small service, ankibase-anki, using anki-cli (opens in a new tab): Anki's own engine (the same Rust core as Anki Desktop) without a desktop app or Docker. Every profile is a folder with its own collection, media and sync login:

# Engine logs
journalctl -u ankibase-anki -f
 
# The collections
ls /opt/ankibase/anki-data/

The engine listens on 127.0.0.1 only and requires an API key, which is generated on first start and kept in /opt/ankibase/anki-data/.env. It keeps an automatic backup of each collection every hour in <profile>/backups/.

Coming from the Docker version

Older versions ran one headless-anki container per account (now called profiles). The first start after updating moves every one over automatically: each container is stopped, its collection and media are copied into /opt/ankibase/anki-data/, the AnkiWeb login is carried over and the container is removed. Docker volumes are left untouched as a safety net, so remove them yourself once everything looks right (docker volume ls).

FeaturesConfiguration