Skip to content
Klutch.sh Docs

Deploying a YOURLS App

Introduction

YOURLS is a lightweight self-hosted URL shortener. This guide shows how to containerize YOURLS with a Dockerfile, connect it to MySQL, persist uploads/config, and deploy it to Klutch.sh over HTTP.

Prerequisites

  • GitHub repository containing your Dockerfile.
  • MySQL database (managed or deployed separately).
  • Klutch.sh project ready in klutch.sh/app.

Project structure

.
└── Dockerfile

Sample Dockerfile

FROM yourls:latest


# Default YOURLS port
ENV YOURLS_PORT=80
EXPOSE 80

Required environment variables

  • YOURLS_SITE – public URL, e.g., https://example-app.klutch.sh
  • YOURLS_USER – admin user
  • YOURLS_PASS – admin password
  • YOURLS_DB_HOST – MySQL host and port
  • YOURLS_DB_USER
  • YOURLS_DB_PASS
  • YOURLS_DB_NAME
  • YOURLS_PORT=80

Optional environment variables

  • YOURLS_DB_PREFIX=yourls_
  • YOURLS_HOURS_OFFSET=0
  • YOURLS_PRIVATE=true to restrict access

Persistence

Persist configuration and data:

  • Mount path: /var/www/html/user
  • Size: minimal unless storing large plugins/assets

Networking

  • Protocol: HTTP
  • Internal port: 80
  • Users reach https://example-app.klutch.sh while Klutch.sh routes to port 80 inside the container.
Terminal window
curl -I http://localhost

Deployment on Klutch.sh

  1. Push your Dockerfile to GitHub.
  2. In klutch.sh/app, create a new app and select GitHub as the source.
  3. Klutch.sh automatically detects the Dockerfile in the repository root.
  4. Select HTTP traffic and set the internal port to 80.
  5. Add environment variables for YOURLS_SITE, admin credentials, and database settings. Mark secrets as sensitive.
  6. Attach a persistent volume at /var/www/html/user for plugins/config.
  7. Deploy. After first boot, log in to the YOURLS admin to add short links.

Verification

  • UI: open https://example-app.klutch.sh/admin and sign in.

  • Quick check:

    Terminal window
    curl -I https://example-app.klutch.sh

Next steps

  • Configure HTTPS at the edge and set YOURLS_SITE accordingly.
  • Enable backups for MySQL and the /var/www/html/user volume.
  • Add custom domain mappings and plugins to extend functionality.