Packistry Deployment with Kamal

This repository provides a streamlined setup for deploying Packistry using Kamal. This guide walks you through configuring, deploying, and managing Packistry with ease.

Prerequisites

Before getting started, make sure the following are installed, configured, and ready for use:

• Kamal: A deployment tool that should be installed on your local machine.
• Server Access: You must have root access to the server and an SSH key properly set up.
• DNS Configuration: An A record must be configured for your domain, pointing to the server's IP address.
• Container Registry Credentials: Ensure you have valid credentials for authentication with your container registry.

Setup Instructions

1. Customize Deployment Configuration

The deployment process is driven by the config/deploy.yml file. Modify this file to match your environment, such as server address and environment variables.

Replace all values enclosed in [] with your specific values. For example, replace [IMAGE NAME] with your actual image name, and [DOMAIN NAME] with your domain name.

service: packistry
image: [IMAGE NAME] # e.g., username/image-name

registry:
  server: ghcr.io/[IMAGE NAME]
  username: [USERNAME] # e.g., myusername
  password:
    - KAMAL_REGISTRY_PASSWORD # value is set in secrets

servers:
  - [DOMAIN NAME] # e.g., 188.245.98.129 or packistryphp.com

volumes:
  - ./data/database.sqlite:/var/www/html/database/database.sqlite
  - ./data/archives:/var/www/html/storage/app/private

proxy:
  host: [DOMAIN NAME] # e.g., packistryphp.com
  ssl: true # Create an A record for the domain name pointing to your server's IP, and Kamal will obtain a free TLS certificate via Let's Encrypt.
  forward_headers: true

env:
  clear:
    APP_URL: https://[DOMAIN NAME] # e.g., https://packistry.j4mie.com
    TRUSTED_PROXIES: 172.18.0.2 # kamal-proxy ip
  secret:
    - APP_KEY # value is set in secrets

builder:
  arch: arm64 # Specify your server's architecture, e.g., amd64 or arm64

2. Configure Secrets

Copy the example secrets file and populate it with the necessary values:

cp .kamal/secrets.example .kamal/secrets

After copying, open the .kamal/secrets file and fill in the required values:

# Token for the GitHub Container Registry. Create one at https://github.com/settings/tokens/new with the "write:packages" scope.
KAMAL_REGISTRY_PASSWORD=your-registry-password
APP_KEY=your-app-key

To generate a secure APP_KEY, run:

echo "base64:$(openssl rand -base64 32)"

3. Initial Deployment Setup

For the first deployment, Kamal will SSH into your server, install Docker, build your container image, and deploy the application.

Run the following command to begin the setup:

kamal setup

Once the setup is complete, create an admin user by accessing the shell within the container:

kamal app exec -i sh

Inside the container, run:

packistry add:user

4. Updates and Subsequent Deployments

To deploy updates or new versions of the Packistry, follow these steps:

Update the Dockerfile: In the root of your project, modify the Dockerfile to use the latest version of the Packistry image. For example, update the version number as follows:

- FROM ghcr.io/packistry/packistry:0.2.1
+ FROM ghcr.io/packistry/packistry:0.3.0

Run the Deployment: After updating the Dockerfile, deploy the updated version by running:

kamal deploy

Kamal will pull the updated container image and deploy it to your server, ensuring that the latest version is running.

Managing Volumes

Application data is persisted in the /root/data directory on the server. This ensures that your data remains intact between deployments and container restarts.

Additional Customization

Feel free to adjust deployment scripts and configurations to suit your specific needs. For advanced customization options, refer to the official Kamal Documentation.