Deploy using Kamal

Deploying with Kamal is the prefer approach when deploying TinyPixel.

# Prerequisites

• You have Ruby and Kamal installed.
• You have a Linux server available that you can SSH into, possibly using DigitalOcean.
• A domain name, or subdomain, with an A record set with your server’s IP.

• A GitHub login and personal access token for authenticating with the container registry.

  This is currently a requirement of Kamal, which is mainly intended for deploying proprietary applications. The TinyPixel container image is publicly available, and we’re hoping Kamal will soon support deploying public images so end users do not need to log in to the registry.

# Deployment Steps

1. On your server, we’ll need to need to create a user with UID 1000, if one does not already exist:

   adduser --uid 1000 rails --disabled-password
   

2. Create a directory owned by UID 1000 for storing the SQLite database files

   mkdir /home/rails/tiny_pixel
   chown rails:rails /home/rails/tiny_pixel
   

3. On your local machine, create a Kamal config.yml to use for deplyoing:

   service: tiny_pixel
   image: ghcr.io/mjc-gh/tiny_pixel
   servers:
     web:
       hosts:
         - __REPLACE_WITH_SERVER_IP__
     workers:
       hosts:
         - __REPLACE_WITH_SERVER_IP__
       cmd: ./bin/jobs
   registry:
     server: ghcr.io
     username:
       - KAMAL_REGISTRY_USERNAME
     password:
       - KAMAL_REGISTRY_PASSWORD
   volumes:
     - "/home/rails/tiny_pixel:/rails/storage"
   builder:
     arch: amd64
   env:
     clear:
        TP_DOMAIN_NAME: __REPLACE_WITH_DOMAIN_NAME__
     secret:
       - RAILS_SECRET_KEY_BASE
   proxy:
     hosts:
       - __REPLACE_WITH_DOMAIN_NAME__
     ssl: true
   

   There are two locations in the servers section where you will need to fill in the IP address of your server. You will also need to change the domain in the env.clear and proxy sections.

   If you are using a different location for storing SQLite database files other than /home/rails/tiny_pixel, you will need to edit the volumes section.

4. Create a .kamal/secrets file using the following template and fill in the values:

   KAMAL_REGISTRY_USERNAME=
   KAMAL_REGISTRY_PASSWORD=
   
   RAILS_SECRET_KEY_BASE=
   

   For the RAILS_SECRET_KEY_BASE, we will need a random value that is sufficiently secure. The simplest way to generate a value is to run:

   openssl rand -hex 64
   

5. Run Kamal to setup your server and deploy TinyPixel

   kamal setup --config-file config.yml --skip-push --version v0.0.1
   kamal deploy --config-file config.yml --skip-push --version v0.0.1
   

6. Login to the system admin using the link generated from running:

   kamal app exec --config-file config.yml -i --reuse --version v0.0.1 "bin/rails tiny_pixel:system_admin_password"
   

Within the system admin, you can create a new login for your TinyPixel instance. Once logged in to the application, you can create new sites, configure them, and add teammates.

# Tips

• Use block storage on your cloud provider to make backups easy. With Digital Ocean, you can attach a small volume block storage and store SQLite data there.