Self-Host ugo
Self-hosting means running ugo on your own server instead of using our hosted service. You get full control over your data, your domain, and your infrastructure. No limits, no recurring fees, and every feature including deep linking into native apps.
If you're not comfortable managing a server, DNS, and Docker, we recommend signing up for a hosted plan instead. You'll be up and running in seconds with zero configuration.
Getting started
ugo is deployed with Once using a pre-built Docker image published to GHCR on every release. You don't need to build anything yourself.
Prerequisites
No local toolchain is required. Once handles everything on the server.
Install Once and ugo
SSH into your server and run:
Once will install Docker if needed, register its background service, and launch the interactive setup. When prompted:
- Choose "Enter a Docker image path"
- Enter:
ghcr.io/fdocr/ugo - Enter the hostname you want to use (e.g.
links.example.com) - Make sure the domain's DNS is already pointed at your server's IP address, otherwise the setup will fail
Once will pull the image, boot the application, and provision an SSL certificate via Let's Encrypt.
Complete the setup wizard
Visit your domain in a browser. You'll see the setup wizard where you'll configure:
Find this in the container logs — run docker ps to get the container ID, then docker logs <container_id> and look for the SETUP CODE line.
Choose a name and confirm the domain for your instance.
Create the first admin account.
Optional — needed for email notifications.
After completing the wizard, your ugo instance is ready to use.
Automatic updates & backups
Updates
Once automatically checks for new image versions and applies updates with zero downtime. The latest tag is updated with every release.
Backups
Once handles backups automatically. ugo includes SQLite backup hooks that create consistent database snapshots. Trigger a manual backup anytime with once backup.
Useful commands
Environment variables
Most configuration is handled through the setup wizard and admin panel. For Cloudflare (orange cloud), set TRUSTED_PROXIES_EXTRA in Once → Settings (s) → Environment (v). See docs/self-hosting.md in the repo for the step-by-step walkthrough.
| Variable | Default | Description |
|---|---|---|
| SECRET_KEY_BASE | Auto (Once) | Session signing and CSRF protection |
| ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY | Auto (first boot) | Encrypts sensitive fields at rest |
| ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY | Auto (first boot) | Deterministic encryption lookups |
| ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT | Auto (first boot) | Salt for key derivation |
| WEB_CONCURRENCY | 1 | Puma worker processes |
| RAILS_MAX_THREADS | 3 | Puma threads per worker |
| JOB_CONCURRENCY | 1 | Solid Queue worker processes |
| SOLID_QUEUE_THREADS | 3 | Solid Queue threads per worker |
| DB_POOL | auto | Optional; defaults to max of thread env vars |
| RAILS_LOG_LEVEL | info | Log verbosity |
| TRUSTED_PROXIES_EXTRA | Unset | CDN CIDRs when behind Cloudflare; run bin/rails trusted_proxies:cloudflare |
Prefer zero configuration?
A ugo.cr account gives you everything you need out of the box: No servers, no DNS, no maintenance. The Dedicated plan offers the same privacy and unlimited usage as self-hosting (within the hardware limits of the instance) without the hassle.
View Hosted Plans