Shlink — a self-hosted URL shortener with detailed visit analytics, QR codes, custom slugs, tags, domains, and a full REST API (a privacy-friendly Bitly alternative). Deployed as an all-in-one host-networked Nomad job: the Shlink app plus a PostgreSQL sidecar with a persistent database volume.
Needs nomad-pack on PATH. The script only adds the nomploy registry and runs this pack.
Source ↗ Project ↗ ★ 5.3k ⚑ Report an issue
Save as values.hcl, edit, then run:
# The name of the Nomad job.
job_name = "shlink"
# The Nomad namespace to deploy into.
namespace = "default"
# The datacenters to deploy to.
datacenters = ["*"]
# The Shlink app image. Pin a tag in production.
image = "shlinkio/shlink:stable"
# The PostgreSQL image for the bundled database.
postgres_image = "postgres:16-alpine"
# Host port for the Shlink API / short-URL server. The container listens on 8080.
port = 8080
# Host port for the co-located PostgreSQL.
db_port = 5432
# Password for the Shlink PostgreSQL user.
db_password = "shlink"
# The domain your short URLs use (DEFAULT_DOMAIN), e.g. s.example.com. Set this to your real domain.
default_domain = "localhost"
# Whether short URLs should use https (IS_HTTPS_ENABLED). Set true when behind a TLS reverse proxy.
is_https_enabled = false
# API key created on first boot (INITIAL_API_KEY), used by the web client and CLI. CHANGE THIS.
initial_api_key = "change-me-initial-api-key"
# Named volume for PostgreSQL data (/var/lib/postgresql/data). Holds all short URLs and visits.
db_data_volume = "shlink_db_data"
# Placement constraints. Pin to the node holding the volume. On a nomploy cluster: attribute = "$${meta.nomploy_control_plane}", operator = "=", value = "true".
constraints = []
# Resources for the Shlink app task.
resources = {
cpu = 500
memory = 512
}
# Resources for the PostgreSQL task.
postgres_resources = {
cpu = 300
memory = 256
}
| Name | Type | Default | Description |
|---|---|---|---|
| job_name | string | "shlink" | The name of the Nomad job. |
| namespace | string | "default" | The Nomad namespace to deploy into. |
| datacenters | list | ["*"] | The datacenters to deploy to. |
| image | string | "shlinkio/shlink:stable" | The Shlink app image. Pin a tag in production. |
| postgres_image | string | "postgres:16-alpine" | The PostgreSQL image for the bundled database. |
| port | number | 8080 | Host port for the Shlink API / short-URL server. The container listens on 8080. |
| db_port | number | 5432 | Host port for the co-located PostgreSQL. |
| db_password key | string | "shlink" | Password for the Shlink PostgreSQL user. |
| default_domain | string | "localhost" | The domain your short URLs use (DEFAULT_DOMAIN), e.g. s.example.com. Set this to your real domain. |
| is_https_enabled | bool | false | Whether short URLs should use https (IS_HTTPS_ENABLED). Set true when behind a TLS reverse proxy. |
| initial_api_key set me | string | "change-me-initial-api-key" | API key created on first boot (INITIAL_API_KEY), used by the web client and CLI. CHANGE THIS. |
| db_data_volume | string | "shlink_db_data" | Named volume for PostgreSQL data (/var/lib/postgresql/data). Holds all short URLs and visits. |
| constraints | list | [] | Placement constraints. Pin to the node holding the volume. On a nomploy cluster: attribute = "$${meta.nomploy_control_plane}", operator = "=", value = "true". |
| resources | object | {
cpu = 500
memory = 512
} | Resources for the Shlink app task. |
| postgres_resources | object | {
cpu = 300
memory = 256
} | Resources for the PostgreSQL task. |
No variables match.
This pack stores data in one Docker named volume:
shlink_db_data
⚠ This pack bundles a database. A cold copy of the volume can be inconsistent — for a reliable backup, dump the DB (pg_dump / mysqldump) or stop the job while backing up.
restic
# Run on the node hosting this pack. Point restic at your repo first: # export RESTIC_REPOSITORY="s3:https://<account>.r2.cloudflarestorage.com/<bucket>" # export RESTIC_PASSWORD="<repo-password>" # export AWS_ACCESS_KEY_ID=<key> AWS_SECRET_ACCESS_KEY=<secret> restic backup \ /var/lib/docker/volumes/shlink_db_data/_data
rclone (sync to S3/R2)
rclone sync /var/lib/docker/volumes/shlink_db_data/_data backup:<bucket>/shlink_db_data
Paths assume the default Docker volume location (/var/lib/docker/volumes). Restore by stopping the job, restoring files into the same volume, and re-running the pack.
Shlink — a self-hosted URL shortener with real analytics. Create short links with custom slugs, tags, and multiple domains; track visits with geolocation and referrers; generate QR codes; and drive it all through a full REST API or the separate web client. A privacy-friendly Bitly alternative.
All-in-one host-networked Nomad job: the Shlink app plus a PostgreSQL sidecar. Migrations run automatically on boot.
nomad-pack registry add nomploy https://github.com/Nomploy/nomad-packs
nomad-pack run shlink --registry=nomploy
| Variable | Default | Description |
|---|---|---|
port |
8080 |
API / redirect port. The container listens on 8080. |
default_domain |
localhost |
DEFAULT_DOMAIN — the domain your short URLs use. Set to your real domain. |
is_https_enabled |
false |
IS_HTTPS_ENABLED — set true behind a TLS reverse proxy. |
initial_api_key |
change-me-… |
INITIAL_API_KEY created on first boot. Change it. |
db_password |
shlink |
PostgreSQL password. |
db_port |
5432 |
Host port for the bundled PostgreSQL. |
db_data_volume |
shlink_db_data |
/var/lib/postgresql/data — all short URLs and visits. |
image |
shlinkio/shlink:stable |
App image. Pin a tag in production. |
resources / postgres_resources |
see variables.hcl |
Per-task resources. |
DEFAULT_DOMAIN is stored on every short URL, so set it correctly before creating links. Manage links
with the initial_api_key via the CLI or the standalone shlink-web-client. Point your short-link domain
at this service and front it with a reverse proxy for TLS. Pin the job to the node holding the volume with
constraints.