Deploy Your URL Shortener to Fly.io in Minutes

• URL Shortener Team • 11 min read
deployment fly.io hosting devops docker

Running your own URL shortener is great, but you need somewhere to host it. Fly.io is an excellent choice - it’s fast, affordable, and their free tier is generous enough to run a production URL shortener at no cost.

In this guide, we’ll walk through deploying the URL Shortener API to Fly.io with persistent storage, custom domains, and monitoring capabilities.

Why Fly.io?

Fly.io stands out for several reasons:

Global Edge Network

Your app runs close to your users with data centers worldwide. This means faster redirects and better user experience.

Generous Free Tier

The free tier includes 3 VMs with 256MB RAM each, 3GB of persistent storage, and 160GB of outbound data transfer. More than enough for most URL shortener deployments.

Simple Deployment

Deploy with a single command. No complex configuration, no YAML nightmares, just straightforward deployment.

Built for Docker

The URL Shortener API comes as a ready-to-use Docker image. Fly.io’s Docker-first approach makes deployment seamless.

Prerequisites

Before we begin, you’ll need:

  • A Fly.io account (free signup at fly.io)
  • Flyctl CLI installed on your machine
  • A valid URL Shortener API license key

Step 1: Install and Authenticate Flyctl

First, install the Fly.io CLI:

Terminal
$ # macOS/Linux
curl -L https://fly.io/install.sh | sh

$ # Windows (PowerShell)
pwsh -Command “iwr https://fly.io/install.ps1 -useb | iex”


$ # Authenticate
fly auth login

The authentication command will open your browser to complete the login process.

Step 2: Create Your App

Choose a unique name for your app or let Fly.io generate one:

Terminal
$ fly apps create your-app-name

$ # Or let Fly.io generate a name
fly apps create

Your app will be accessible at https://your-app-name.fly.dev.

Step 3: Configure Your Deployment

Download the fly.toml configuration file from the url-shortener-api repository. This file defines your app’s configuration.

Key settings to customize:

app = "your-app-name"
primary_region = "iad"

Available regions:

  • iad - Virginia, USA (East Coast)
  • lax - California, USA (West Coast)
  • fra - Frankfurt, Germany
  • syd - Sydney, Australia
  • sin - Singapore

Choose the region closest to your users for the best performance.

Step 4: Set Your License Key

Store your license key securely as a secret:

Terminal
$ fly secrets set LICENSE_KEY=your-actual-license-key

Secrets are encrypted and never exposed in logs or configuration files.

Step 5: Create Persistent Storage

Your URL data needs to persist across deployments. Create a volume:

Terminal
$ fly volumes create url_shortener_data \
  --region iad \
  --size 1

Important notes about volumes:

  • The volume name must match the source in fly.toml (default: url_shortener_data)
  • The region must match your app’s primary_region
  • Size is in GB (1 GB minimum, sufficient for thousands of URLs)
  • You can increase size later but cannot decrease it

Step 6: Deploy!

Now for the moment of truth:

Terminal
$ fly deploy

Fly.io will pull the Docker image, configure your app, mount the persistent volume at /data, and start your service. The whole process takes about 30 seconds.

Step 7: Get Your API Key

Your URL shortener generates a random API key on first startup. Retrieve it from the logs:

Terminal
$ fly logs

Look for output showing the generated API key. Save this securely - you’ll need it for all API requests.

Step 8: Test Your Deployment

Verify everything is working:

Terminal
$ # Check status
fly status
$ # Create a short URL
curl -X POST https://your-app-name.fly.dev/shorten \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'
$ # Test the redirect
curl -L https://your-app-name.fly.dev/abc12345

If you see a successful redirect, congratulations! Your URL shortener is live.

Advanced Configuration

Enable Click Tracking

Track analytics for your shortened URLs:

Terminal
$ fly secrets set CLICK_TRACKING_PATH=/data/clicks.jsonl

Note: Review GDPR and privacy considerations before enabling tracking in production.

Add a Custom Domain

Brand your short URLs with your own domain:

Terminal
$ fly certs add yourdomain.com

Follow the instructions to add the required DNS records (A and AAAA) to your domain registrar. Fly.io will automatically provision SSL certificates.

Scale Your Resources

Need more power? Scale vertically or horizontally:

Terminal
$ # Increase memory
fly scale memory 512

$ # Add more instances
fly scale count 2


$ # Upgrade to dedicated CPU
fly scale vm dedicated-cpu-1x

The default configuration (256MB, shared CPU) handles thousands of redirects per day comfortably.

Backup and Monitoring

Create Backups

Back up your URL data regularly:

Terminal
$ fly ssh console -C "tar -czf /tmp/backup.tar.gz /data"
fly ssh sftp get /tmp/backup.tar.gz ./backup.tar.gz

Consider setting up a cron job to automate this process.

Monitor Logs

Keep an eye on your app with real-time logs:

Terminal
$ # Follow live logs
fly logs -f

$ # View recent logs
fly logs —recent

Troubleshooting

App Not Starting?

Check these common issues:

  1. Verify your license key: fly secrets list
  2. Check the logs: fly logs
  3. Confirm volume is mounted: fly volumes list

Volume Not Mounting?

Ensure the volume name in your fly.toml matches the volume you created, and that both are in the same region.

Need More Storage?

Expand your volume (you can increase but not decrease):

Terminal
$ fly volumes list
fly volumes extend <volume-id> --size 5

Cost Optimization

The default configuration fits comfortably within Fly.io’s free tier:

  • 3 shared-cpu-1x VMs (256MB RAM each)
  • 3GB persistent storage
  • 160GB outbound data transfer

To minimize costs:

  1. Use the auto_stop_machines = true setting (enabled by default in the provided fly.toml)
  2. Start with minimal resources and scale as needed
  3. Use shared CPUs instead of dedicated ones
  4. Monitor your usage via fly dashboard

For most use cases, the free tier is more than sufficient for production workloads.

Conclusion

Deploying your URL shortener to Fly.io gives you a globally distributed, fast, and reliable service with minimal effort. The combination of Docker-based deployment, persistent storage, and automatic SSL makes Fly.io an excellent choice for hosting your URL shortener.

The free tier is generous enough for serious production use, and you can scale up seamlessly as your needs grow. Plus, with custom domains and click tracking, you have all the features of commercial URL shorteners while maintaining complete control over your data.

Ready to deploy? Follow this guide and you’ll have your URL shortener running in production in less than 10 minutes!

For more information, check out the URL Shortener API documentation and Fly.io documentation.

← Back to Blog