Koillection

Prerequisites

• An active Azure subscription, an SSH key pair, and a VNet and subnet in the target region.
• Standard_B2s (2 vCPU / 4 GiB RAM) is a good starting point. Scale up for very large catalogues or many concurrent users.
• NSG inbound rules: allow 22/tcp from your management network and 80/tcp (HTTP) from wherever you will browse the catalogue. Add 443/tcp if you enable HTTPS.

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure portal, choose Create a resource, search the Marketplace for Koillection by SecureAnyCloud, 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). Then choose Review + create and Create.

Step 2 - Deploy from the Azure CLI

# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:koillection-ubuntu-24-04:default:latest
az vm create \
  --resource-group <your-rg> \
  --name koillection \
  --image sac1647283583153:koillection-ubuntu-24-04:default:latest \
  --size Standard_B2s \
  --admin-username azureuser \
  --generate-ssh-keys \
  --public-ip-sku Standard

Open HTTP to reach the web UI:

az vm open-port --resource-group <your-rg> --name koillection --port 80 --priority 900

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 - Confirm the Koillection stack is running

nginx serves Koillection on port 80, in front of php8.5-fpm, and a local PostgreSQL database backs it. PostgreSQL is bound to 127.0.0.1, so no database port is exposed to the network.

for u in postgresql php8.5-fpm nginx; do printf '%-18s %s\n' "$u:" "$(systemctl is-active $u)" done ss -tln | awk '/:80 /{print "nginx "$4} /127.0.0.1:5432 /{print "postgres "$4}' | sort -u

All three units report active, and only nginx listens on a public port:

postgresql: active php8.5-fpm: active nginx: active nginx 0.0.0.0:80 nginx [::]:80 postgres 127.0.0.1:5432

Why the site may not answer for the first minute. On the first boot, nginx is deliberately held back until koillection-firstboot.service has generated the secrets of this VM and created its administrator account. This is a security control, not a fault (see Step 10). If nginx reports inactive immediately after launch, wait a minute and check again.

Step 5 - Retrieve the first-boot administrator credentials

On the first boot of your instance, a one-shot service generates a fresh application secret and API signing keypair, rotates the PostgreSQL password, and builds the database schema. It also creates an administrator with a fresh random password and writes the credentials to a root-only file. Read them with:

sudo cat /root/koillection-credentials.txt

The file is mode 0600 and owned by root. The administrator password is unique to this VM:

sudo stat -c '%a %U:%G %n' /root/koillection-credentials.txt

600 root:root /root/koillection-credentials.txt

Step 6 - Sign in to the web UI

Browse to http://<vm-public-ip>/ and sign in as the generated administrator (username admin) with the password from Step 5. Koillection opens on your collections overview:

Change the administrator password right away. Open the avatar menu in the top right and choose Profile.

Step 7 - Build your first collection

Choose Collections, then the + button. Give the collection a title such as Vinyl Records, and save. Open the collection and use + again to add items.

Each item can carry its own typed fields: text, numbers, dates, prices, ratings, lists, countries, links and images. To give every item in a collection the same fields, define them once as a Template and set it as the default template of the collection.

Each collection chooses how it displays its items. The default is a picture grid. To switch to List display, choose the pencil icon, then Items display. Set Display mode to List and tick the fields you want as columns. The catalogue then appears as a sortable table of your own fields:

Open an item to see its full record, including every custom field value:

Alongside collections, Koillection provides tags and tag categories, wishlists, loan tracking, photo albums, an activity history, saved searches and statistics. All are reachable from the left-hand navigation.

Step 8 - Use the REST API

Koillection ships a documented REST API. Authenticate with the administrator credentials to receive a JSON Web Token, then send it as a bearer token. Browse the interactive documentation at http://<vm-public-ip>/api/docs.

TOKEN=$(curl -s -X POST http://127.0.0.1/api/authentication_token \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"<KOILLECTION_ADMIN_PASSWORD>"}' | jq -r .token)
curl -s -H "Authorization: Bearer $TOKEN" -H 'Accept: application/ld+json' \
  http://127.0.0.1/api/collections | jq -c '{totalItems, collections: [.member[].title]}'

After you create a few collections, the following request returns them as JSON:

{"totalItems":3,"collections":["Vinyl Records","Board Games","Vintage Cameras"]}

The token is signed with the keypair generated for this VM on first boot. An unauthenticated call is refused:

curl -s -o /dev/null -w 'GET /api/collections (no token) : HTTP %{http_code}\n' \
  -H 'Accept: application/ld+json' http://127.0.0.1/api/collections

GET /api/collections (no token) : HTTP 401

Step 9 - Version and stack

The image ships Koillection 1.8.3 on PHP 8.5, PostgreSQL 16 and nginx:

echo -n 'Koillection version: ' grep -oE '"version": *"[0-9.]+"' /var/www/koillection/composer.json | head -1 | grep -oE '[0-9.]+' php -v | head -1 sudo -u postgres psql -tAc 'SHOW server_version' | awk '{print $1}' nginx -v

Koillection version: 1.8.3 PHP 8.5.8 (cli) (built: Jul 3 2026 05:09:00) (NTS) 16.14 nginx version: nginx/1.24.0 (Ubuntu)

Step 10 - The first-boot security model

No shared or default credentials ship in the image. On first boot, koillection-firstboot.service does the following:

• Generates a fresh per-VM application secret and JWT passphrase.
• Rotates the PostgreSQL koillection role password and writes it into /var/www/koillection/.env.local.
• Regenerates the API signing keypair (the image ships none).
• Builds the database schema from empty.
• Creates the administrator account with a fresh per-VM random password.
• Writes the credentials to /root/koillection-credentials.txt (root only, 0600).

The order matters. Koillection presents an unauthenticated setup page whenever it has no users, and whoever reaches that page first becomes an administrator. This image therefore holds nginx back until first boot has finished. nginx.service carries a condition on the sentinel file that the first-boot service writes last, so the application is never reachable while it has no administrator. If first boot fails, the site stays down rather than opening unprotected.

systemctl is-active koillection-firstboot.service
systemctl is-enabled koillection-firstboot.service
sudo stat -c '%a %U:%G' /root/koillection-credentials.txt grep -h ConditionPathExists /etc/systemd/system/nginx.service.d/10-sac-koillection.conf

active enabled 600 root:root ConditionPathExists=/var/lib/sac/data/koillection-firstboot.done

New user accounts are created by an administrator from within the application; there is no anonymous sign-up.

Step 11 - Enable HTTPS with a custom domain (recommended)

Koillection stores personal data and image uploads, so put it behind TLS before you load a real catalogue. Open 443/tcp in your NSG first. Point a DNS A record at the public IP of your VM, then install a Let's Encrypt certificate with certbot.

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d collection.your-domain.com

Certbot obtains the certificate and reconfigures nginx to serve Koillection over HTTPS and redirect HTTP to HTTPS. Koillection derives every URL from the request host, so no application configuration change is needed.

Step 12 - Maintenance

• Upload quota. Each account has a disk-space allowance for images, and the administrator account is provisioned with 10 GiB. Adjust the allowance per user from Administration > Users.
• Add more users from Administration > Users. Each user gets their own private collections.
• Scraping. Koillection can populate item fields from a URL with the Scrapers feature. This image does not include Chromium, so scraping uses the standard HTTP fetch path. Static pages work, while sites that build their content entirely in the browser return less. For the headless-browser path, install chromium and chromium-driver on the VM and restart php8.5-fpm.
• Security updates are applied automatically by unattended-upgrades on Ubuntu. systemd manages PHP, PostgreSQL and nginx and restarts them on failure.
• Back up the PostgreSQL koillection database together with the uploaded images:

text sudo -u postgres pg_dump koillection | gzip > ~/koillection-$(date +%F).sql.gz sudo tar czf ~/koillection-uploads-$(date +%F).tar.gz -C /var/www/koillection/public uploads

Support

SecureAnyCloud provides 24/7 support for this image by email (sales@secureanycloud.com) and live chat. Support covers deployment, first-boot credential retrieval, collections, templates and custom fields, user management, the REST API, backup and restore, HTTPS and custom domains, upgrades and troubleshooting.

For billing or subscription changes, contact sales@secureanycloud.com.

Deploy on Azure

Launch Koillection on Ubuntu 24.04 LTS on Azure with 24/7 support from SecureAnyCloud.

View this image

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com