Shortener Demo

This repository is a URL shortener demo. It uses:

• Rails 8
• PostgreSQL
• Sidekiq
• Redis
• Kamal for deployment

Run Locally With The Devcontainer

The easiest way to run the app locally is in the included devcontainer.

1. Open the repository in VS Code.
2. Choose Dev Containers: Reopen in Container.
3. Wait for the container to build. The devcontainer runs bin/setup --skip-server after creation, which installs gems and prepares the database.
4. Copy the sample environment file:

cp .example.env .env

5. Copy .example.env to .env for local development:

cp .example.env .env

Then fill your own environment variables.

6. Start the app:

bin/dev

bin/dev starts:

• the Rails web server on port 3000
• Tailwind in watch mode
• Sidekiq

The devcontainer forwards port 3000, so the app should be available at http://localhost:3000.

Environment Variables

Copy .example.env to .env for local development:

cp .example.env .env

The sample file includes:

• SECRET_KEY_BASE: Rails secret for cookies and encrypted data
• DB_NAME: base PostgreSQL database name
• DB_HOST: database host, which should stay postgres in the devcontainer
• DB_USERNAME: PostgreSQL username
• DB_PASSWORD: PostgreSQL password
• REDIS_URL: Redis connection string used by Sidekiq and the Rails cache, the hostname should stay redis

Because config/database.yml derives multiple databases from DB_NAME, Rails will create names like:

• <DB_NAME>
• <DB_NAME>_cache
• <DB_NAME>_queue
• <DB_NAME>_cable
• <DB_NAME>_test

Deployment Files

.kamal/secrets

Kamal reads secrets from .kamal/secrets. In this project, that file maps secret names to environment variables:

• KAMAL_REGISTRY_PASSWORD
• SECRET_KEY_BASE
• DB_NAME
• DB_USERNAME
• DB_PASSWORD

deploy.sh.example

deploy.sh.example is a template wrapper around Kamal. Copy it to deploy.sh, replace the placeholder values, and keep the real file out of version control in .gitignore.

cp deploy.sh.example deploy.sh
chmod +x deploy.sh

It exports the environment variables Kamal needs. First commit your changes if any, then run one of two commands:

• ./deploy.sh setup: first-time server setup, it installs Docker on your server, pulls and boots the accessory containers (Redis and PostgreSQL).
• ./deploy.sh deploy: build and deploy a new release after each change, any new changes must be committed first.

.example.env

.example.env is only for local development. It is not used directly by Kamal deploys, but it documents the same application-level values you will also provide during deployment.

config/deploy.yml

config/deploy.yml is the main Kamal configuration file.

• service: names the deployed application
• image: Docker image repository to build and push
• asset_path: path where Rails assets are served from in the container
• servers: defines the machines running the web process and the Sidekiq process
• proxy: enables HTTPS and tells Kamal which domain should route to the app
• registry: configures the container registry credentials; the password comes from KAMAL_REGISTRY_PASSWORD
• env.clear: non-secret environment variables passed to the containers
• env.secret: secret environment variables loaded through .kamal/secrets
• volumes: persistent Docker volumes, here used for Active Storage files
• builder: remote Docker build settings, including target architecture and Ruby version build arg
• accessories: supporting services deployed alongside the app, here PostgreSQL and Redis
• aliases: convenience commands for common Kamal tasks like logs, console, and migrations

Important Values To Replace

Before deploying, update these placeholders in config/deploy.yml:

• <dockerhub-username>
• <server-ip-address-or-hostname>
• <domain-name>

You should also make sure the following values are consistent across config/deploy.yml, .kamal/secrets, and your deployment script:

• Docker registry credentials
• database name and credentials
• SECRET_KEY_BASE
• app hostnames