Gokapi on Ubuntu 24.04 on Azure User Guide

Overview

This guide covers the deployment and configuration of Gokapi 2.2.4 on Ubuntu 24.04 on Azure using cloudimg Azure Marketplace images. Gokapi is a lightweight open source self-hosted file-sharing server: you sign in to an admin panel, upload files, and Gokapi gives you a shareable download link for each one, with per-file controls for expiry, download count, an optional password and image hotlinking. It is a lean, privacy-respecting alternative to third-party file-transfer services — your files stay on infrastructure you control.

The image installs the official Gokapi v2.2.4 release binary (a single, statically-linked Go binary) verified by SHA-256 at install time, and ships the AGPL-3.0 licence text alongside it. The backend is a local SQLite database with files stored on the VM's own disk, so there is no external database, no object store and no database port to secure.

Security model. Gokapi's own first-run setup wizard is unauthenticated, so cloudimg completes setup at build time — no open setup wizard is ever exposed on your instance. Gokapi binds to 127.0.0.1:53842 only and is fronted by nginx on port 80. The admin / management surface (/admin, /api/, /users, uploads, ...) is guarded by per-VM HTTP Basic Auth (a password minted uniquely on first boot) layered over Gokapi's own admin login — defence in depth on everything that can change state. The public download endpoints (/d, /downloadFile, /dh, /h) are intentionally left open so the links you share resolve for their recipients without a login, which is the whole point of a file-sharing server. The only ports exposed are SSH (22) and the web UI (80, with 443 available for you to add TLS).

What is included:

• Gokapi 2.2.4 official release binary at /usr/local/bin/gokapi (SHA-256-verified)

• gokapi.service systemd unit running the server bound to 127.0.0.1:53842

• nginx reverse proxy on port 80: public download links open, admin surface behind per-VM HTTP Basic Auth

• gokapi-firstboot.service systemd oneshot that mints the per-VM admin password and Basic Auth password on first boot

• A local SQLite database at /var/lib/gokapi/data/gokapi.sqlite with files stored under /var/lib/gokapi/data

• A credential self-test at /usr/local/sbin/gokapi-credcheck.sh

• The AGPL-3.0 licence text at /usr/local/share/gokapi/LICENSE.md

• Ubuntu 24.04 LTS base with latest security patches applied at build time

• 24/7 cloudimg support with guaranteed 24 hour response SLA

Prerequisites

• An active Azure subscription

• A subscription to the Gokapi on Ubuntu 24.04 listing on Azure Marketplace

• An SSH public key for VM authentication

• A virtual network and subnet in the target region

Recommended virtual machine size: Standard_B2s (2 vCPU, 4 GB RAM). Gokapi is lightweight; scale up only if you share very large files or serve many concurrent downloads.

Step 1: Deploy from the Azure Portal

Navigate to Marketplace in the Azure Portal, search for Gokapi, select the cloudimg publisher entry, and click Create.

On the Networking tab attach a network security group that allows inbound TCP 22 from your management IP range and TCP 80 from the client networks that will use the file-sharing UI and download links. The admin surface on port 80 is protected by a per-VM Basic Auth password, but you should still restrict source ranges and add TLS (port 443) before sharing anything sensitive — see Step 9.

Click Review + create, wait for validation, then Create. Deployment takes around two minutes.

Step 2: Deploy from the Azure CLI

RG="gokapi-prod"
LOCATION="eastus"
az group create --name "$RG" --location "$LOCATION"

az vm create \
  --resource-group "$RG" \
  --name gokapi-01 \
  --image <publisher>:<offer>:<sku>:latest \
  --size Standard_B2s \
  --admin-username azureuser \
  --generate-ssh-keys \
  --public-ip-sku Standard

# Allow SSH (22) and the web UI + download links (80) from your trusted ranges
az vm open-port --resource-group "$RG" --name gokapi-01 --port 22 --priority 1001
az vm open-port --resource-group "$RG" --name gokapi-01 --port 80 --priority 1002

Replace <publisher>:<offer>:<sku> with the URN shown on the Marketplace listing's Usage Information tab.

Step 3: Connect via SSH

ssh azureuser@<vm-public-ip>

Use the private key that matches the public key you supplied at deploy time. The login user for this image is azureuser.

Step 4: Verify the Gokapi Service

Confirm the Gokapi server and the nginx proxy are running, and check the listening sockets. Gokapi binds to 127.0.0.1:53842 only — it is reachable off the VM solely through nginx on port 80. The AGPL-3.0 licence ships with the image.

gokapi --version
systemctl is-active gokapi nginx
sudo ss -ltn | grep -E ':80 |:53842'
head -2 /usr/local/share/gokapi/LICENSE.md

Expected output:

Gokapi v2.2.4
active
active
LISTEN 0  4096  127.0.0.1:53842  0.0.0.0:*
LISTEN 0   511    0.0.0.0:80      0.0.0.0:*
LISTEN 0   511       [::]:80         [::]:*
                    GNU AFFERO GENERAL PUBLIC LICENSE
                       Version 3, 19 November 2007

Step 5: Retrieve Your Per-VM Credentials

On the first boot of your virtual machine, gokapi-firstboot.service generated two secrets unique to your instance — the Gokapi admin login password and the nginx Basic Auth password for the admin surface — and wrote them to a root-only file. Retrieve them with:

sudo cat /root/gokapi-credentials.txt

The file reports the URL, the Basic Auth credential (guards the admin surface) and the Gokapi admin login:

gokapi.url=http://<vm-public-ip>/
gokapi.basicauth.user=admin
gokapi.basicauth.pass=<generated-per-vm>
gokapi.admin.user=admin
gokapi.admin.pass=<generated-per-vm>

A shipped self-test confirms the whole credential model without printing any secret — it proves the public surface is open, the admin surface rejects missing and wrong Basic Auth, and the per-VM admin login round-trips:

sudo bash /usr/local/sbin/gokapi-credcheck.sh

Expected output:

OK

Step 6: Understand the Access Model

Gokapi is a file-sharing server, so its download links are public — recipients fetch them with no login. Everything that can change state is protected: the admin surface requires the per-VM HTTP Basic Auth password (and then Gokapi's own admin login on top). You can see both halves with curl:

BASIC_PW=$(sudo grep '^gokapi.basicauth.pass=' /root/gokapi-credentials.txt | cut -d= -f2-)
curl -s -o /dev/null -w 'public /login   -> HTTP %{http_code}\n' http://127.0.0.1/login
curl -s -o /dev/null -w '/admin no auth  -> HTTP %{http_code}\n' http://127.0.0.1/admin
curl -s -o /dev/null -w '/admin wrong pw -> HTTP %{http_code}\n' -u 'admin:definitely-wrong' http://127.0.0.1/admin
curl -s -o /dev/null -w '/admin per-VM   -> HTTP %{http_code}\n' -u "admin:$BASIC_PW" http://127.0.0.1/admin

Expected output:

public /login   -> HTTP 200
/admin no auth  -> HTTP 401
/admin wrong pw -> HTTP 401
/admin per-VM   -> HTTP 200

Step 7: Sign In and Share Files

In a browser, go to http://<vm-public-ip>/admin. The browser first prompts for HTTP Basic Auth — enter user admin and the gokapi.basicauth.pass from Step 5. Gokapi then shows its own login page; sign in with user admin and the gokapi.admin.pass from Step 5:

Once signed in you land on the Upload panel. Drag files onto the drop zone (or click to select), set an optional download limit, expiry and password, and each uploaded file appears in the table below with its own share ID and a set of actions — copy the share URL, open the share dialog, download, edit or delete:

Step 8: How Recipients Download

Share the link Gokapi generates (for example http://<vm-public-ip>/d/<id>/<filename>). Recipients open it in any browser with no login and see a clean download page for just that file:

You can automate the same flow with the Gokapi API. Create an API key in the API menu of the admin panel, then upload and share files programmatically. The uploaded file's UrlDownload resolves anonymously through nginx:

# On any client, with an API key created in the admin panel's API menu:
curl -s -H "apikey: <your-api-key>" -F 'file=@report.pdf' \
  http://<vm-public-ip>/api/files/add | jq -r .FileInfo.UrlDownload
# -> http://<vm-public-ip>/d/<id>/report.pdf   (open with no login)

Step 9: Put TLS in Front (Production)

The UI and download links are served over plain HTTP on port 80. Before sharing anything sensitive, terminate TLS in front of Gokapi. Add a Let's Encrypt certificate to the bundled nginx:

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

Point your DNS A record at the VM's public IP first, and open port 443 in the network security group. Certbot updates the bundled nginx vhost in place, preserving the access model. After adding a custom domain, update Gokapi's own external URL so generated links use it:

sudo -u gokapi GOKAPI_CONFIG_DIR=/etc/gokapi GOKAPI_DATA_DIR=/var/lib/gokapi/data \
  /usr/local/bin/gokapi --reconfigure   # follow the prompts, or edit ServerUrl in /etc/gokapi/config.json
sudo systemctl restart gokapi

Step 10: Change the Passwords

To rotate the Basic Auth password on the admin surface, update the htpasswd file and reload nginx:

sudo htpasswd /etc/nginx/.gokapi.htpasswd admin
sudo systemctl reload nginx

To rotate the Gokapi admin login password non-interactively:

sudo -u gokapi GOKAPI_CONFIG_DIR=/etc/gokapi GOKAPI_DATA_DIR=/var/lib/gokapi/data \
  /usr/local/bin/gokapi --deployment-password '<new-password>'
sudo systemctl restart gokapi

Step 11: Connect Object Storage (Optional)

By default files are stored on the VM's local disk with metadata in SQLite. To store files in an S3-compatible object store instead, run Gokapi's reconfigure wizard and provide your bucket, region, keys and endpoint:

sudo systemctl stop gokapi
sudo -u gokapi GOKAPI_CONFIG_DIR=/etc/gokapi GOKAPI_DATA_DIR=/var/lib/gokapi/data \
  /usr/local/bin/gokapi --reconfigure
sudo systemctl start gokapi

See the Gokapi cloud storage documentation for the exact S3 settings, including the CORS configuration required for encrypted downloads.

Step 12: Managing the Gokapi Service

# Status and logs
systemctl status gokapi --no-pager
sudo journalctl -u gokapi -n 100 --no-pager

# Restart after changing configuration
sudo systemctl restart gokapi

# nginx (the reverse proxy)
sudo nginx -t && sudo systemctl reload nginx

Architecture Summary

• Gokapi 2.2.4 — a single statically-linked Go binary at /usr/local/bin/gokapi, run as the non-root gokapi service account under systemd, bound to 127.0.0.1:53842.

• nginx on port 80 — public download/share endpoints open; admin/management endpoints behind per-VM HTTP Basic Auth.

• Local SQLite at /var/lib/gokapi/data/gokapi.sqlite, with files on the VM's own disk — no external database, no database port.

• First-boot service mints a per-VM Gokapi admin password and a per-VM Basic Auth password, sets the public URL, and writes both to a root-only credentials file. No shared or default credential ships in the image.

Support

cloudimg provides 24/7 technical support for this Gokapi image by email (support@cloudimg.co.uk) and live chat, with a guaranteed 24 hour response SLA and a one hour average response time for critical issues. We help with deployment, retrieving and rotating the first-boot credentials, adding HTTPS and a custom domain, connecting S3-compatible storage, using the Gokapi API and CLI uploader, configuring file expiry and download limits, upgrades and patch management, and troubleshooting. For billing, subscription changes or refund requests, contact support@cloudimg.co.uk.

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.