Shoko Server on Ubuntu 24.04 on Azure User Guide

Overview

Shoko Server is the open source, self hosted server for organising an anime media collection (MIT licensed). It hashes every file in your library, matches it against AniDB using your own AniDB account, and builds a browsable catalogue of series, episodes and metadata that you manage from a polished Web UI and a full REST API. The cloudimg image runs the official Shoko Server container (shokoanime/server, pinned to a stable release) bound to loopback behind an nginx reverse proxy on port 80, keeps all Shoko state on a dedicated Azure data disk, and mints a unique administrator password on the first boot of every VM before the web front door is opened. Backed by 24/7 cloudimg support.

What is included:

• Shoko Server (stable v5.3.x) from the official shokoanime/server Docker image, running as shoko-server.service
• nginx on :80 as a reverse proxy to the loopback Shoko backend (127.0.0.1:8111), with WebSocket upgrade headers for Shoko's realtime events
• A per-VM administrator account (Default) minted on first boot and recorded in a root-only file - with the always-blank-password Family Friendly admin removed and the blank/default logins proven rejected
• A dedicated 40 GiB Azure data disk at /var/lib/shoko holding the SQLite database, settings and downloaded metadata
• SQLite as the datastore - single node, no separate database service to run
• shoko-server.service + nginx.service as systemd units, enabled and active
• 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet + subnet in the target region. Standard_B2s (2 vCPU / 4 GiB RAM) is a good starting point. NSG inbound: allow 22/tcp from your management network and 80/tcp. Shoko serves plain HTTP on port 80; for production, terminate TLS in front of it with your own domain. To match files against AniDB you will need your own free AniDB account - it is never baked into the image.

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for Shoko Server by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size; under Administrator account choose SSH public key and paste your key; under Inbound port rules allow SSH (22) and HTTP (80). Review the dedicated data disk on the Disks tab, then Review + create -> Create.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name shoko \
  --image <cloudimg-shoko-image-urn> \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard

az vm open-port --resource-group <your-rg> --name shoko --port 80 --priority 1010

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 - Confirm the services are running

systemctl is-active shoko-server.service nginx.service

Both report active. On first boot the Shoko container starts, its first-boot service drives the Shoko setup API to mint a per-VM administrator, and nginx is opened only once that password is in place.

Step 5 - Retrieve your admin password

The Default administrator password is generated uniquely on the first boot of your VM and written to a root-only file:

sudo cat /root/shoko-credentials.txt

This file contains SHOKO_URL, SHOKO_ADMIN_USER (Default) and SHOKO_ADMIN_PASSWORD. Store the password somewhere safe.

Step 6 - Confirm the health endpoint

nginx serves an unauthenticated health endpoint on :80 for load balancers and probes:

curl -s http://localhost/healthz; echo

It returns ok. Shoko's own unauthenticated startup-status endpoint reports the server state and, once ready, Started:

curl -s http://localhost/api/v3/Init/Status

Step 7 - Sign in to the Web UI

Browse to http://<vm-public-ip>/ and sign in as user Default with the password from Step 5.

After signing in you land on the dashboard. Because the image ships without any media, the collection is empty - this is the correct starting state, exactly like a fresh Shoko install. The dashboard shows the queue processor, the unrecognised-files panel and your collection statistics.

Step 8 - Connect your AniDB account

Shoko identifies your files by matching them against AniDB. Open Settings -> AniDB, enter your own AniDB username and password under Login Options, and click Test. Your AniDB credentials are yours - they are never stored in the image and are entered only here, on your own VM.

Step 9 - Point Shoko at your media

Open Settings -> Import to review how files are imported (renaming, moving, the recognised video extensions), then add an Import Folder pointing at where your anime files live on the VM (for example a folder under /var/lib/shoko or an attached share). Shoko hashes each file, matches it against AniDB and builds your collection automatically.

Step 10 - Verify authentication from the command line (optional)

Shoko's authentication endpoint rejects a blank or wrong password and accepts the per-VM Default password, returning an apikey. Using the SHOKO_ADMIN_PASSWORD from Step 5, the round-trip looks like this (substitute your own password for <SHOKO_ADMIN_PASSWORD>):

# authenticate as the per-VM Default admin and read the current user
TOKEN=$(curl -s -X POST -H 'Content-Type: application/json' \
  -d '{"user":"Default","pass":"<SHOKO_ADMIN_PASSWORD>","device":"cli"}' \
  http://localhost/api/auth | jq -r '.apikey')
curl -s -H "apikey: $TOKEN" http://localhost/api/v3/User/Current | jq '{Username, IsAdmin}'

A correct password returns an apikey and the current-user object shows "Username": "Default", "IsAdmin": true; a blank password, a wrong password, and the removed Family Friendly account are all rejected, and an anonymous request to the API returns HTTP 401. The screenshot below shows the round-trip taken during the image build (the per-VM secret is redacted).

Step 11 - Confirm data lives on the dedicated disk

All Shoko state - the SQLite database, settings and downloaded metadata - is stored on the dedicated Azure data disk so it survives OS changes and can be resized independently:

findmnt /var/lib/shoko

The mount is backed by a separate Azure data disk captured into the image and re-provisioned on every VM.

Maintenance

• Admin users: manage users from Settings -> User Management in the Web UI.
• AniDB: your AniDB login lives under Settings -> AniDB; it is supplied by you and never shipped in the image.
• Data: the SQLite database, settings and metadata all live under /var/lib/shoko on the dedicated data disk - snapshot it to back Shoko up.
• TLS: Shoko serves plain HTTP on port 80; front it with TLS (e.g. certbot) and your own domain before production use.
• Upgrades: pull a newer Shoko image and restart the service, for example sudo docker pull shokoanime/server:<new-tag> then edit the tag in /etc/systemd/system/shoko-server.service and run sudo systemctl daemon-reload && sudo systemctl restart shoko-server.service.
• Security patches: unattended-upgrades remains enabled so the OS continues to receive security updates automatically.

Support

cloudimg provides 24/7 expert support for this image. Contact support@cloudimg.co.uk.