oier/shlink-docker-compose
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: Shlink docker compose stack

Browse Source 
Self-hosted Shlink URL shortener with the official web dashboard,
backed by PostgreSQL 16. Designed to sit behind a reverse proxy
that terminates TLS.

- shlink server exposed on host port 8500
- shlink-web-client dashboard exposed on host port 8501
- postgres 16 kept internal, persisted via named volume
- dashboard preconfigured via SHLINK_PUBLIC_URL + INITIAL_API_KEY
- .env.example documents required variables; .env is gitignored

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Oier Bravo
2026-05-11 02:59:53 +02:00
commit 2c386efc9c
4 changed files with 167 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

83
README.md Normal file
View File

@@ -0,0 +1,83 @@
# Shlink Docker Compose
Self-hosted [Shlink](https://shlink.io) URL shortener with the official web dashboard, backed by PostgreSQL. Intended to run behind a reverse proxy that terminates TLS.
## Stack
| Service | Image | Container port | Default host port |
|---|---|---|---|
| `shlink` | `shlinkio/shlink:stable` | `8080` | `8500` |
| `shlink-dashboard` | `shlinkio/shlink-web-client:stable` | `8080` | `8501` |
| `shlink-db` | `postgres:16-alpine` | `5432` | not exposed |
## Quick start
```bash
cp .env.example .env
# Edit .env — set DEFAULT_DOMAIN, SHLINK_PUBLIC_URL, INITIAL_API_KEY, POSTGRES_PASSWORD
docker compose up -d
```
Generate strong secrets:
```bash
openssl rand -hex 32 # INITIAL_API_KEY
openssl rand -hex 24 # POSTGRES_PASSWORD
```
## Environment variables
| Variable | Required | Description |
|---|---|---|
| `DEFAULT_DOMAIN` | yes | Bare host used to build short URLs (e.g. `s.example.com`). No scheme. |
| `SHLINK_PUBLIC_URL` | yes | Full public URL of the Shlink API (e.g. `https://s.example.com`). Used by the dashboard. |
| `INITIAL_API_KEY` | yes | API key created on first boot. Also preconfigures the dashboard. |
| `POSTGRES_PASSWORD` | yes | PostgreSQL password. |
| `IS_HTTPS_ENABLED` | no | `true` (default) if your reverse proxy terminates TLS. Set `false` for plain HTTP. |
| `GEOLITE_LICENSE_KEY` | no | MaxMind GeoLite2 license key for IP geolocation. |
| `TIMEZONE` | no | Defaults to `UTC`. |
| `POSTGRES_DB` | no | Defaults to `shlink`. |
| `POSTGRES_USER` | no | Defaults to `shlink`. |
| `SHLINK_SERVER_PORT` | no | Host port for the Shlink API. Defaults to `8500`. |
| `SHLINK_DASHBOARD_PORT` | no | Host port for the dashboard. Defaults to `8501`. |
## Reverse proxy
Two hostnames recommended:
- `s.example.com` → `http://127.0.0.1:8500` — Shlink API and short URL redirects.
- `shlink-admin.example.com` → `http://127.0.0.1:8501` — Dashboard UI.
The proxy must terminate TLS and forward `X-Forwarded-Proto` / `X-Forwarded-For` so Shlink renders `https://` short URLs and logs the correct client IP.
`DEFAULT_DOMAIN` must match the hostname your proxy serves the API on, otherwise generated short URLs will be wrong.
## Persistence
Two named volumes:
- `shlink-data` — Shlink cache and runtime files.
- `shlink-db-data` — PostgreSQL data directory.
Back both up before upgrades.
## Common operations
```bash
docker compose logs -f shlink # follow server logs
docker compose exec shlink shlink --help # CLI inside the container
docker compose pull && docker compose up -d # upgrade images
docker compose down # stop (data preserved)
```
Create an additional API key:
```bash
docker compose exec shlink shlink api-key:generate
```
## Notes
- `INITIAL_API_KEY` only takes effect on the very first boot, before the database is initialized. Changing it later does nothing — use `api-key:generate` instead.
- The dashboard ships preconfigured with one server pointed at `SHLINK_PUBLIC_URL`. The browser must be able to reach that URL; it is not a server-to-server call.
- Postgres is intentionally not exposed on the host. Connect via `docker compose exec shlink-db psql -U shlink`.