Skip to main content

Shlink on Google Cloud Run

Shlink on Google Cloud Run

Shlink is a self-hosted, open-source URL shortener with detailed visit analytics, QR code generation, and a full REST API. This module deploys Shlink on Cloud Run v2 on top of the App_CloudRun foundation, which provisions and manages the shared Google Cloud infrastructure.

This guide focuses on the cloud services Shlink uses and how to explore and operate them from the Google Cloud Console and the command line. For the mechanics common to every Cloud Run application — service identity, ingress and load balancing, scaling and concurrency, CI/CD, Cloud Armor, IAP, Binary Authorization, VPC Service Controls, backups, and the deployment lifecycle — refer to the App_CloudRun foundation guide rather than repeating them here.

Running Shlink in your own GCP project costs about $67.80/month in Google Cloud charges; RAD's module fee is a one-time 75 credits (or 67.5 credits in a RAD-managed project), covering setup and support -- not the ongoing cloud bill, which Google bills you directly in your own project or RAD meters hourly in credits in a RAD-managed one. Or see the GKE guide for the alternative deployment target; either way, if you deploy into a RAD-managed project you can pause the whole thing for free when you are not using it -- see Pause it for free below.

What you pay on RAD​

Your own projectRAD-managed project
Module fee75 credits, once67.5 credits, once (10% lower)
Build timemetered in credits as the build runs (a few credits, typically)same
Google Cloud running cost~$67.80/month, billed to your own billing account at Google's list price~26 credits/day, metered hourly by RAD at list price plus margin

Default running cost in your own project

ResourceUS$/month (Google list price, us-central1)
Cloud Run, 1x vCPU / 0.5 GiB (scaleToZero)$10.78
Cloud SQL for PostgreSQL, 1 vCPU / 3.75 GB, zonal, 10 GB SSD$51.02
Cloud NAT and networking$5.00
Cloud Storage (add-ons, backups)$1.00
Total$67.80

How it compares​

  • Shlink's own footprint here (1x vCPU / 0.5 GiB) is smaller than this reference class, so an even cheaper VPS tier would do just as well, but sized to the smallest commonly-quoted class for comparison: Hetzner CPX22 (2 vCPU/4GB) runs about $24/month, a DigitalOcean 2 vCPU/4GB Droplet is also $24/month, and a GCP Compute Engine e2-standard-2 (2 vCPU/8GB) is about $49/month -- plus the admin's own time for backups, security patches and upgrades, which RAD's managed Cloud SQL, Secret Manager and monitoring cover for you -- but RAD's price is never meant to beat a VPS, only to replace the admin time a VPS still needs.
  • A URL shortener answers simple redirects continuously but cheaply -- the database is the main standing cost here, not the shortener service itself.

Pause it for free: delete a RAD-managed project, restore it when you need it​

This is the headline for a RAD-managed project. Deleting a RAD-managed project first unlinks its billing, then asks Google to delete the project outright -- Google's own 30-day recoverable soft delete. Unlike deleting one module, this does not tear down Cloud SQL, any VM or the compute resource one by one: the whole project simply stops, and nothing is charged while it waits, because billing is already unlinked.

Restoring, within 30 days and only by the project's owner, asks Google to undelete the project and reattaches its billing account, then asks you to run Update on each deployment to confirm everything came back. Because nothing was individually destroyed, that Update finds the same resources already there -- it is a check, not a rebuild, and an Update never charges the module fee again. This costs only a handful of credits (under US$1) in total for a typical 2-3-deployment chain.

What this needs: you must own the project (not one RAD only manages billing for), you must restore it yourself within 30 days -- after that Google deletes it for good -- and restoring is admitted like creating a new project, so your purchased credit balance must still clear the tier's floor (100 credits for the sandbox tier most study/demo use fits). Google says most services are fully working again within 36 hours of a restore.

One real gap: nightly backups are written to a bucket inside the project, and that bucket has Cloud Storage's soft-delete explicitly turned off, so it is very likely gone as soon as you delete the project -- even though the project itself is recoverable for 30 days. If you have customised the app and want to keep that work, copy a backup out (to Google Drive, or a bucket outside the project) before deleting. For a default install with nothing irreplaceable in it, this does not matter.

Pay only while you use it, the other way: delete and redeploy​

In your own project (or once you are past the 30-day restore window above), the alternative is to delete Shlink outright and redeploy it later. A redeploy costs the module fee again, plus the builds -- roughly 75 + 3-6 credits of build time.

Deleting saves money only once Shlink would otherwise sit unused long enough to clear that redeploy cost against its own daily running cost -- against the own-project total above, that works out to about 4 days or more. Most of the running cost here is usually the database; it stops only when nothing else in the project uses it, so deleting this app while something else shares the project saves only this app's own compute part.

Keep data first: nightly backups go to a bucket inside the deployment and are deleted with it, so copy the latest backup out before deleting if you want to keep it.

Lab sessions and Managed Environments​

  • Lab sessions, for training: a trainer runs a session for a class. Each participant gets the app in their own Google Cloud project for 15 minutes to 24 hours, within an allowance the trainer sets. Either the trainer funds every place, or each participant pays for their own. Everything is deleted when the session ends and unused credits go back to the trainer.
  • Managed Environments, for consultancies: a partner runs the app for a client from a ring-fenced wallet it funds, and settles with the client directly. If the wallet runs low, billing pauses and the data is kept, so nobody receives an unexpected charge. At the end the partner hands the project over and the deployments become the client's own.
  • Credits can be bought in more than 20 currencies, including XAF, XOF, NGN, GHS, KES and ZAR, by card, bank transfer or mobile money.

Sources (8 October 2026): Google Cloud Billing Catalog API list prices; radmodules.dev/pricing for RAD's own fees and daily-credit estimates; https://cloud.google.com/resource-manager/docs/delete-restore-projects for the pause/restore mechanics.

1. Overview​

Shlink runs as a PHP (RoadRunner) container on Cloud Run v2. The deployment wires together a deliberately small set of Google Cloud services — Shlink keeps all of its state in PostgreSQL, so there is no NFS share or object-storage bucket to manage:

CapabilityGoogle Cloud serviceNotes
ComputeCloud Run v21 vCPU / 512 MiB by default, scale-to-zero (min_instance_count = 0)
DatabaseCloud SQL for PostgreSQL 15Required — holds short URLs, visits, tags, and API keys
DB connectivityCloud SQL Auth Proxy (Unix socket)enable_cloudsql_volume = true; libpq-friendly socket, no public IP
SecretsSecret ManagerDatabase password + auto-generated INITIAL_API_KEY
Cache / locksRedis (optional)Disabled by default; only useful for multi-instance caching/locking
IngressCloud Run URL / Cloud Load BalancingDefault run.app URL, optional external HTTPS LB + custom domain

Sensible defaults worth knowing up front:

  • PostgreSQL 15 is the supported engine (database_type = "POSTGRES_15", DB_DRIVER = "postgres"). Shlink connects through the Cloud SQL Auth Proxy Unix socket — libpq accepts the socket directory as its host, so no TCP/SSL configuration is needed.
  • DB_USER / DB_NAME are injected by the foundation with tenant-scoped names and deliberately not set by the module — the db-init job creates that same user and database, so everything lines up automatically.
  • INITIAL_API_KEY is auto-generated (32 characters), stored in Secret Manager, and injected as a secret env var. Shlink reads it on first start to bootstrap its first REST API key — you never create a key by hand.
  • Migrations run automatically on container start. The official image handles schema install and upgrades; no separate migrate step exists.
  • Scale-to-zero by default. Shlink is a stateless request/response app (redirects + REST API); it costs nothing when idle. The trade-off is a ~5–15 s cold start on the first request after idling.
  • Health probes target /rest/health — a public, unauthenticated endpoint that returns HTTP 200 with {"status":"pass"}. Shlink has no web homepage; / returns 404 by design.
  • DEFAULT_DOMAIN is left empty because the run.app URL is not known until after deploy — set it post-deploy so generated short URLs use the right host. IS_HTTPS_ENABLED=true is pre-set.
  • The database password is generated automatically and stored in Secret Manager, injected as DB_PASSWORD.

2. Google Cloud Services & How to Explore Them​

All commands assume PROJECT and REGION are set. Service and resource names are reported in the deployment Outputs.

A. Cloud Run — the Shlink service​

Shlink runs as a Cloud Run v2 service that autoscales by request load between the minimum (0) and maximum (3) instance counts. Each deployment creates an immutable revision; traffic can be split across revisions for safe rollouts.

  • Console: Cloud Run → select the service for revisions, traffic, logs, and metrics.
  • CLI: 
    gcloud run services list --project "$PROJECT" --region "$REGION"
    gcloud run services describe <service-name> --project "$PROJECT" --region "$REGION"
    gcloud run revisions list --service <service-name> --project "$PROJECT" --region "$REGION"

See App_CloudRun for scaling, concurrency, execution environment, and traffic splitting.

B. Cloud SQL for PostgreSQL 15​

Shlink stores everything — short URLs, visit records, tags, domains, and API keys — in a managed Cloud SQL for PostgreSQL 15 instance. The service connects privately through the Cloud SQL Auth Proxy over a Unix socket (no public IP). On first deploy a db-init Job creates the application database and user.

  • Console: SQL → select the instance for connections, backups, flags, metrics.
  • CLI: 
    gcloud sql instances list --project "$PROJECT"
    gcloud sql instances describe <instance-name> --project "$PROJECT"
    gcloud sql connect <instance-name> --user=<db-user> --project "$PROJECT"

The instance name, database, user, and password secret are in the Outputs. See App_CloudRun for the connection model, backups, and password rotation.

C. Secret Manager​

Two secrets are managed automatically: the database password (created by the foundation, injected as DB_PASSWORD) and the initial API key (created by Shlink_Common, injected as INITIAL_API_KEY). Plaintext never appears in configuration.

  • Console: Security → Secret Manager.
  • CLI: 
    gcloud secrets list --project "$PROJECT" --filter="name~shlink"
    gcloud secrets versions access latest \
      --secret="$(gcloud secrets list --project "$PROJECT" \
        --filter='name~shlink AND name~initial-api-key' --format='value(name)' --limit=1)" \
      --project "$PROJECT"

See App_CloudRun for injection and rotation details.

D. Redis (optional)​

Shlink can use Redis for caching and distributed locks — worthwhile only when running several instances concurrently. It is disabled by default (enable_redis = false); a single-digit max_instance_count deployment works fine without it.

  • Console: Memorystore → Redis (if using a managed instance).
  • CLI: 
    redis-cli -h <redis-host> ping

E. Networking & ingress​

The service is reachable at its run.app URL by default. An external HTTPS load balancer with a custom domain (the natural fit for a branded short domain such as s.example.com), Cloud CDN, and Cloud Armor can be layered on; ingress settings and VPC egress control connectivity.

  • Console: Cloud Run (service URL); Network services → Load balancing.
  • CLI: 
    gcloud run services describe <service-name> --region "$REGION" --format='value(status.url)'
    gcloud compute addresses list --project "$PROJECT"

See App_CloudRun.

F. Cloud Logging & Monitoring​

Container logs flow to Cloud Logging; Cloud Run and Cloud SQL metrics flow to Cloud Monitoring. An uptime check against /rest/health is provisioned by default, with a check-failure alert wired to support_users.

  • Console: Logging → Logs Explorer; Monitoring → Uptime checks / Alerting.
  • CLI: 
    gcloud run services logs read <service-name> --project "$PROJECT" --region "$REGION" --limit 50
  • First-deploy database setup. A db-init Job (image postgres:15-alpine) connects to Cloud SQL via the Auth Proxy socket and idempotently creates the application user and database, grants privileges (including GRANT <user> TO postgres so ownership can be set), and signals the proxy sidecar to shut down so the Job completes. The job runs on every apply and is safe to re-run.
  • Migrations on start. Shlink's official image runs its database migrations automatically on every container start — first boot installs the schema, upgrades apply schema changes with no manual step. The startup probe allows up to ~300 s (failure_threshold = 30 × 10 s) for first-boot migrations.
  • API-first — no homepage. Shlink is a headless server: / returns 404 by design. Everything is driven through the REST API (/rest/v3/...) using the X-Api-Key header, or through a separately hosted shlink-web-client UI pointed at this server.
  • First-run access. Retrieve the bootstrap API key from Secret Manager (see §2C) and use it immediately: 
    API_KEY=$(gcloud secrets versions access latest --secret=<initial-api-key-secret> --project "$PROJECT")
    curl -s -X POST "<service-url>/rest/v3/short-urls" \
      -H "X-Api-Key: $API_KEY" -H "Content-Type: application/json" \
      -d '{"longUrl": "https://cloud.google.com/run"}'
  • DEFAULT_DOMAIN after deploy. Shlink embeds its public host into every generated short URL. The service URL is unknown at plan time, so DEFAULT_DOMAIN ships empty — set it (via the environment_variables input on an Update) to the run.app hostname or your custom short domain once known.
  • Geolocation is opt-in. Visit geolocation needs a MaxMind GeoLite2 license: set GEOLITE_LICENSE_KEY in environment_variables. Without it, visits are still recorded — just not geolocated.
  • Scaling constraints. Instances are stateless (all state in PostgreSQL), so scale-out is safe. If you raise max_instance_count well beyond the default 3 and rely on Shlink's cached counters/locks, enable Redis (enable_redis = true).
  • Health verification: 
    curl -s "<service-url>/rest/health"
    # {"status":"pass","version":"...","links":{...}}

4. Configuration Variables​

Variables are grouped exactly as they appear on the deployment platform. Only settings specific to or notable for Shlink are listed; every other input is inherited from App_CloudRun with its standard behaviour.

Group 1 — Project & Identity​

VariableDefaultDescription
project_id(required)Target Google Cloud project.
regionus-central1Region for the service and regional resources.

Group 2 — Deployment Environment​

VariableDefaultDescription
tenant_iddemoShort suffix that makes resource names unique per environment.
support_users[]Emails granted project access and monitoring alerts.
resource_labels{}Labels applied to all resources.

Group 3 — Application Identity​

VariableDefaultDescription
application_nameshlinkBase name for resources. Do not change after first deploy.
display_nameShlinkFriendly name shown in the Console.
application_versionstableShlink image version tag (e.g. 4.4.0); increment to trigger a new build.
admin_usernameshlinkNot used by Shlink (it authenticates with API keys, not admin accounts). Retained for interface parity.

Group 4 — Runtime & Scaling​

VariableDefaultDescription
deploy_applicationtrueSet false to provision infrastructure only.
cpu_limit1000mCPU per instance — 1 vCPU comfortably serves redirects and API calls.
memory_limit512MiMemory per instance (gen2 minimum).
min_instance_count0Scale-to-zero. Costs nothing idle; first request after idle takes a ~5–15 s cold start. Set 1 for latency-sensitive links.
max_instance_count3Maximum instances. Enable Redis before raising this significantly.
container_port8080Shlink's native HTTP port.
enable_cloudsql_volumetrueCloud SQL Auth Proxy Unix socket — the libpq-friendly connection Shlink expects.
enable_image_mirroringtrueMirrors the image into Artifact Registry to avoid Docker Hub rate limits.
execution_environmentgen2Cloud Run gen2 (recommended).

All other inputs follow standard App_CloudRun behaviour.

Group 5 — Environment Variables & Secrets​

VariableDefaultDescription
environment_variables{}Plain-text env vars. Notable Shlink options: DEFAULT_DOMAIN (public short-URL host — set post-deploy), GEOLITE_LICENSE_KEY (MaxMind key for visit geolocation). DB_DRIVER=postgres, DB_PORT=5432, IS_HTTPS_ENABLED=true are injected automatically.
secret_environment_variables{}Extra Secret Manager references. DB_PASSWORD and INITIAL_API_KEY are wired automatically.

All other inputs follow standard App_CloudRun behaviour.

Group 6 — Access & Ingress Control​

Standard IAP / ingress / VPC egress inputs (enable_iap, ingress_settings, vpc_egress_setting). Note that a shortener's redirect endpoints must stay publicly reachable — IAP in front of Shlink also gates every short link. All other inputs follow standard App_CloudRun behaviour.

Groups 7–10 — Backup, CI/CD, Custom SQL, Domain & CDN​

Standard App_CloudRun behaviour (backup_schedule, enable_cicd_trigger, enable_binary_authorization, enable_custom_sql_scripts, application_domains, enable_cdn, enable_cloud_armor, image-retention inputs). application_domains is where a branded short domain is attached. All inputs follow standard App_CloudRun behaviour.

Group 11 — Storage & Filesystem​

VariableDefaultDescription
enable_nfsfalseShlink stores all data in PostgreSQL — no shared filesystem is needed.
create_cloud_storage / gcs_volumesoff / []No buckets are provisioned; Shlink needs none.

All other inputs follow standard App_CloudRun behaviour.

Group 12 — Database Backend​

VariableDefaultDescription
database_typePOSTGRES_15Shlink's supported Cloud SQL engine here — do not change.
db_nameshlinkBase database name (tenant-prefixed by the foundation). Immutable after first deploy.
db_usershlinkBase application user (tenant-prefixed). Immutable after first deploy.
database_password_length32Generated password length (16–64).
db_password_env_var_nameDB_PASSWORDPre-set — Shlink reads DB_PASSWORD directly.

All other inputs follow standard App_CloudRun behaviour.

Group 13 — Jobs & Scheduled Tasks​

VariableDefaultDescription
initialization_jobs[]Leave empty to use the built-in db-init job (postgres:15-alpine).
cron_jobs[]Recurring jobs triggered by Cloud Scheduler.

Group 14 — Observability & Health​

VariableDefaultDescription
startup_probeHTTP /rest/health, 30 s initial delay, failure_threshold = 30Allows up to ~300 s for first-boot migrations.
liveness_probeHTTP /rest/health, 30 s delay, period 30 s/rest/health is unauthenticated, so liveness stays enabled.
uptime_check_configdisabled, path /rest/healthCloud Monitoring uptime check + failure alert.

All other inputs follow standard App_CloudRun behaviour.

Group 21 — Redis Cache​

VariableDefaultDescription
enable_redisfalseOptional caching/locking for multi-instance setups; unnecessary at the default scale.
redis_host / redis_port / redis_auth"" / 6379 / ""Redis endpoint details when enabled.

Group 22 — VPC Service Controls & Audit Logging​

Standard App_CloudRun behaviour (enable_vpc_sc, vpc_cidr_ranges, vpc_sc_dry_run, organization_id, enable_audit_logging).

5. Outputs​

Returned on a successful deployment — the quickest way to locate and explore the running resources.

OutputDescription
service_nameCloud Run service name.
api_urlDefault run.app URL of the service.
health_check_url<api_url>/rest/health — curl it to confirm the deployment is live (Shlink has no homepage; / 404s).
service_locationRegion the service runs in.
stage_servicesStage-specific service URLs (Cloud Deploy).
load_balancer_ip / load_balancer_urlExternal HTTPS load balancer IP / URL (when enabled).
database_instance_nameCloud SQL instance name.
database_name / database_userApplication database name / user (tenant-scoped).
database_password_secretSecret Manager secret holding the DB password.
database_host / database_portDB endpoint / port.
storage_bucketsCreated Cloud Storage buckets (empty — Shlink needs none).
network_name / network_exists / regionsVPC network, presence, regions.
container_image / container_registryDeployed image and Artifact Registry repo.
monitoring_enabled / monitoring_notification_channels / uptime_check_namesMonitoring status, channels, uptime checks.
initialization_jobsNames of the setup jobs (db-init).
deployment_id / tenant_id / resource_prefixNaming identifiers.
project_id / project_numberProject identifiers.
cicd_enabled / github_repository_url / github_repository_owner / github_repository_name / cicd_configurationCI/CD status and details.
artifact_registry_repository / cloudbuild_trigger_name / cloudbuild_trigger_idRegistry and build trigger.
vpc_sc_enabled / vpc_sc_perimeter_name / vpc_sc_dry_run_modeVPC-SC status.
audit_logging_enabled / artifact_registry_cmek_enabledAudit logging and CMEK status.

6. Configuration Pitfalls & Sensible Defaults​

Risk: Critical (data loss / outage / security) — High (service degraded) — Medium (cost or partial degradation) — Low (minor).

SettingSensible valueRiskConsequence if wrong
database_typePOSTGRES_15CriticalShlink is wired for PostgreSQL here (DB_DRIVER=postgres); another engine breaks startup.
db_name / db_userset onceCriticalImmutable after first deploy; renaming recreates the DB/user and destroys all short URLs and visit data.
environment_variables DB_USER / DB_NAMEnever set manuallyCriticalOverrides the foundation's tenant-scoped names → password authentication failed for user "shlink". Leave them unset.
container_port8080CriticalShlink's native port; mismatching it fails all health probes.
enable_cloudsql_volumetrueCriticalShlink expects the Auth Proxy Unix socket; disabling it breaks the DB connection path.
probe / uptime path/rest/healthHigh/ returns 404 by design — probing it kills healthy revisions.
startup_probe failure_threshold30HighReducing it can kill the container before first-boot migrations complete.
DEFAULT_DOMAINset post-deployHighLeft empty, generated short URLs may carry the wrong host; set it to the run.app or custom domain.
enable_iapfalse for public linksHighIAP in front of Shlink gates every short-link redirect behind Google sign-in.
max_instance_count w/o Redis3MediumMany instances without Redis lose shared caching/locking; enable enable_redis before scaling wide.
min_instance_count0 (default) or 1Medium0 is near-free but adds a ~5–15 s cold start to the first redirect after idle.
GEOLITE_LICENSE_KEYset if analytics matterLowWithout it visits are recorded but not geolocated.
enable_nfs / create_cloud_storagefalse / offLowWasted cost — Shlink keeps all state in PostgreSQL.

For the foundation behaviour referenced throughout — service identity, scaling and concurrency, ingress and load balancing, CI/CD, Cloud Armor, IAP, Binary Authorization, VPC-SC, backups, and image mirroring — see App_CloudRun. Shlink-specific application configuration shared with the GKE variant is described in Shlink_Common.

Need RAD to do something it does not do yet? Request it on the roadmap, or vote on what is already there.

By · Google Cloud certified: ACE · PCA · PCD · PDE · PSE · CDL

Last updated on