Grimmory

Search the Azure Marketplace for Grimmory, choose the plan, and create the VM.

In the networking step, attach an NSG that allows inbound TCP 22 (SSH) and TCP 80 (the web console) from your client networks only. For production, put a TLS reverse proxy in front of port 80.

No other port needs to be open. The bundled MariaDB stays on a private container network, and the application's own port 6060 is published to loopback only, so nginx is the only ingress.

RG="grimmory-prod"; LOCATION="eastus"; VM_NAME="grimmory-01" IMAGE_URN="sac1647283583153:grimmory-ubuntu-24-04:default:latest" SSH_KEY="$(cat ~/.ssh/id_rsa.pub)" az group create --name "$RG" --location "$LOCATION" az network vnet create -g "$RG" --name gr-vnet --address-prefix 10.114.0.0/16 --subnet-name gr-subnet --subnet-prefix 10.114.1.0/24 az network nsg create -g "$RG" --name gr-nsg az network nsg rule create -g "$RG" --nsg-name gr-nsg --name allow-ssh --priority 100 \
  --source-address-prefixes "<your-mgmt-cidr>" --destination-port-ranges 22 --access Allow --protocol Tcp az network nsg rule create -g "$RG" --nsg-name gr-nsg --name allow-web --priority 110 \
  --source-address-prefixes "<your-mgmt-cidr>" --destination-port-ranges 80 --access Allow --protocol Tcp
# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:grimmory-ubuntu-24-04:default:latest
az vm create -g "$RG" --name "$VM_NAME" --image "$IMAGE_URN" \
  --size Standard_B2s --storage-sku StandardSSD_LRS \
  --admin-username azureuser --ssh-key-values "$SSH_KEY" \
  --vnet-name gr-vnet --subnet gr-subnet --nsg gr-nsg --public-ip-sku Standard

The library data disk is part of the image, so Azure creates and mounts it for you automatically. There is no extra disk to attach.

ssh azureuser@<vm-ip>

All services start automatically on first boot, after grimmory-firstboot.service has generated this instance's secrets, brought the bundled database up and claimed the administrator. First boot also brings the container stack up for the first time, so it typically completes within a minute or two of the VM reporting ready.

Check that the services are running:

sudo systemctl is-active grimmory nginx
sudo test -f /var/lib/sac/data/grimmory-firstboot.done && echo FIRSTBOOT_DONE
sudo ss -tlnH | awk '{print $1, $4}' | sort -u

Expected output: both units are active and first boot has completed. Only SSH and nginx are on a public address. The application port stays on loopback, and the database is on no host port at all.

active active FIRSTBOOT_DONE LISTEN 0.0.0.0:22 LISTEN 0.0.0.0:80 LISTEN 127.0.0.1:6060 LISTEN 127.0.0.53%lo:53 LISTEN [::]:22 LISTEN [::]:80

In the output:

• The application is published on 127.0.0.1:6060, so it is reachable only from the VM itself.
• The port 53 entry is the local systemd-resolved DNS stub.
• The bundled MariaDB appears nowhere in the list, because it lives on a private container network with no host port.
• nginx is the sole ingress.

To see the two containers, run sudo docker compose -f /opt/grimmory/docker-compose.yml ps.

Every instance generates its own administrator password and database password on first boot and writes them to a root-only file. Read it with:

sudo ls -l /root/grimmory-credentials.txt
sudo cat /root/grimmory-credentials.txt

The file is mode 600, owned by root. It contains the console URL, the administrator username and password, and the database credentials. Sign in with those values, then change the administrator e-mail address and password under Settings > Users.

Grimmory creates its first administrator through a one-time setup endpoint that the API accepts only while no users exist. This image claims that administrator during first boot, before nginx starts, so nobody can reach your instance and claim it first.

Confirm that the setup endpoint is closed:

curl -s http://127.0.0.1/api/v1/setup/status

Expected output: setup has already been completed on this instance.

{"data":true,"message":"Initial setup has already been completed.","status":200,"timestamp":"..."}

A protected endpoint must refuse both an anonymous caller and a forged token:

curl -s -o /dev/null -w 'anonymous: %{http_code}\n' http://127.0.0.1/api/v1/users/me
curl -s -o /dev/null -w 'forged token: %{http_code}\n' http://127.0.0.1/api/v1/users/me \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJub2JvZHkifQ.not-a-valid-signature'

Expected output:

anonymous: 401 forged token: 401

Run the commands below:

curl -s http://127.0.0.1/api/v1/healthcheck df -h /var/lib/grimmory | tail -1 free -m | head -2 swapon --show

The output shows the following:

• The health endpoint reports the running version.
• The dedicated 64 GiB library volume is mounted at /var/lib/grimmory.
• The whole stack sits comfortably inside 4 GB.
• swapon --show prints nothing, because the image ships with no swap at all.

Browse to http://<vm-ip>/ and sign in with the administrator username and password from the credentials file.

Create a library from the Libraries section of the sidebar and point it at the container library folder /books. On the host, this is the data volume path /var/lib/grimmory/books.

Copy your EPUB, PDF, MOBI, comic or audiobook files there. Grimmory scans them, extracts titles, authors and covers, and shelves them.

sudo install -d -o grimmory -g grimmory -m 0750 /var/lib/grimmory/books ls -ld /var/lib/grimmory/books /var/lib/grimmory/bookdrop

Then copy your own files in and hand them to the grimmory user. Replace the source path with your own:

sudo cp ~/my-collection/*.epub /var/lib/grimmory/books/
sudo chown -R grimmory:grimmory /var/lib/grimmory/books

You can also drop files into the watched auto-import folder (the container path /bookdrop, on the host /var/lib/grimmory/bookdrop), or upload them straight from the browser with the upload button in the toolbar.

The All Books view shows the shelved collection with covers. The filter panel lets you narrow by author, format, read status, publisher, language or year.

Click any book to open it in the built-in reader. EPUB, PDF and comic formats all render in the browser, with per-user reading position, bookmarks and a progress indicator. You can stop on one device and resume on another.

Audiobooks open in the built-in player with the same per-user position tracking.

Settings exposes reader and player preferences per format, metadata provider configuration, user administration, e-mail delivery, OIDC single sign-on and the task manager.

Create an account for each reader under Settings > Users and give each one only the permissions they need. Each user keeps their own shelves and progress.

Grimmory also serves an OPDS catalogue and supports Kobo and KOReader sync, so the same library is reachable from a dedicated e-reader.

Metadata fetching from providers such as Amazon, Google, Open Library and Hardcover requires outbound internet access from the VM. It is optional and disabled until you configure it.

• Application: ghcr.io/grimmory-tools/grimmory:v3.3.1, Spring Boot on Temurin JDK 25, published on 127.0.0.1:6060
• Web console: Angular, built into the same image and served by the application
• Database: bundled MariaDB 11.4 container (grimmory-mariadb) on a private container network, with database and role grimmory
• Reverse proxy: nginx.service on TCP 80, hardened (server tokens off, host guard, sensitive paths denied)
• Compose project: /opt/grimmory/docker-compose.yml, managed by grimmory.service
• Library volume: 64 GiB disk at /var/lib/grimmory (config/ = database, data/, books/, bookdrop/)
• Secrets file: /opt/grimmory/.env (mode 600, generated at first boot)
• Credentials: /root/grimmory-credentials.txt (mode 600)
• Corresponding source: /usr/share/grimmory/source/ and /usr/share/doc/grimmory/

The Java heap is capped at 768 MB and MariaDB's buffer pool at 128 MB, so the two never contend on a 2 vCPU instance. If you move to a larger VM and want to raise the heap, edit JDK_JAVA_OPTIONS in /opt/grimmory/docker-compose.yml, then run sudo systemctl restart grimmory.

Grimmory is licensed under the GNU Affero General Public License version 3. Section 13 requires that anyone who interacts with the program over a network is offered the corresponding source of the running version. This instance satisfies that on disk, with no network access required:

cat /usr/share/doc/grimmory/SOURCE-OFFER.txt cd /usr/share/grimmory/source && sha256sum -c grimmory-3.3.1-source.tar.gz.sha256

The complete unmodified v3.3.1 source tree is shipped as a release tarball at /usr/share/grimmory/source/. The licence text is at /usr/share/doc/grimmory/LICENSE. The written offer names the exact running image digest and all of the paths.

SecureAnyCloud makes no modifications to Grimmory itself. This image supplies only the Docker Compose project, systemd units, a hardened nginx vhost and the first-boot credential bootstrap.

Run a quick health check of the whole stack:

sudo systemctl is-active grimmory nginx
sudo nginx -t

For deeper investigation, read the service journals and the container logs. They print a lot of output, so run them on their own:

sudo systemctl status grimmory
sudo journalctl -u grimmory-firstboot --no-pager sudo docker logs --tail 100 grimmory
sudo docker compose -f /opt/grimmory/docker-compose.yml ps

The stack reads its per-instance secrets from /opt/grimmory/.env. After you edit the compose project, restart it with sudo systemctl restart grimmory.

Database maintenance runs inside the bundled MariaDB container and reads this instance's password straight from the credentials file, so there is nothing to type or paste:

sudo docker exec grimmory-mariadb mariadb -u grimmory \
  -p"$(sudo sed -n 's/^grimmory\.db\.pass=//p' /root/grimmory-credentials.txt)" \
  grimmory -e "SELECT COUNT(*) AS tables FROM information_schema.tables WHERE table_schema='grimmory';"

To back up the library, snapshot the data volume and dump the database the same way:

sudo docker exec grimmory-mariadb mariadb-dump -u grimmory \
  -p"$(sudo sed -n 's/^grimmory\.db\.pass=//p' /root/grimmory-credentials.txt)" \
  grimmory > ~/grimmory-backup.sql