Hylius CI/CD & Deployment Guide

Hylius provides a Deployment Trinity that lets you manage your own servers with the same ease as platforms like Vercel or Render — while keeping full control of your infrastructure.

1. The Deployment Trinity

2. Server Provisioning (hylius setup)

Before you can deploy, your VPS must be prepared with Docker and security hardening. See the full Provisioning Guide for details.

bashhylius setup

What it does: - Detects OS (Ubuntu, Debian, or Alpine) - Installs Docker Engine and Docker Compose plugin - Installs Railpack (zero-config container builder — no Dockerfile needed) - Configures UFW firewall to allow ports 22, 80, and 443

Headless/CI Mode: When CI=true or GITHUB_ACTIONS=true is set, setup skips all prompts and reads from environment variables: HYLIUS_HOST, HYLIUS_USER, HYLIUS_PORT, HYLIUS_PASSWORD, HYLIUS_SSH_KEY.

3. Manual Deployment (hylius deploy)

Push your code directly to your VPS from the command line.

bashhylius deploy

How it works: 1. Clones your Git repo into a timestamped release directory on the VPS 2. Builds a Docker image using Dockerfile → Railpack (in that order) 3. Starts the new container(s) 4. Atomically symlink-swaps to the new release (zero-downtime) 5. Old container is gracefully stopped

Deployment strategy auto-detection:

See the full Deployment Guide for framework-specific tips.

4. GitHub Actions CI/CD (hylius ci-generate)

Automate deployments so that every git push to main updates your server.

Step 1 — Generate the workflow

Run the following in your project root:

bashhylius ci-generate

You'll be prompted to choose a template:

• Deploy Only (recommended) → creates .github/workflows/hylius-deploy.yml
• Full Pipeline (Setup + Deploy) → creates .github/workflows/hylius-pipeline.yml

Or skip the prompt with a flag:

bashhylius ci-generate --full   # Full pipeline

Step 2 — Configure GitHub Secrets

Go to your GitHub Repository → Settings → Secrets and variables → Actions and add:

Step 3 — Push and watch it deploy

Commit and push the generated workflow file:

bashgit add .github/workflows/hylius-deploy.yml
git commit -m "ci: add hylius deploy workflow"
git push

Every subsequent push to main will automatically deploy your app.

5. Dagger CI Pipeline (hylius ci-generate --dagger)

For teams that need GHCR image builds, pull request preview deployments, and build caching, Hylius offers a Dagger-powered pipeline.

bashhylius ci-generate --dagger
# or target a specific branch:
hylius ci-generate --dagger --branch production

What gets created:

How the Dagger pipeline works:

git push → GitHub Actions → Dagger → builds image → pushes to ghcr.io → 
  notifies Hylius Dashboard → Dashboard pulls image → zero-downtime swap

Required secrets for Dagger:

Automatic fallback: If your repo has no Dockerfile, the pipeline automatically falls back to Railpack to build and push the image — no extra configuration needed.

6. Full Pipeline (hylius ci-generate --full)

The full pipeline template includes an optional setup job that runs hylius setup before deploying:

yaml# Triggered via GitHub UI (workflow_dispatch) with run_setup: true
jobs:
  setup:
    if: github.event.inputs.run_setup == 'true'
    ...
  deploy:
    needs: [setup]
    if: always() && (needs.setup.result == 'success' || needs.setup.result == 'skipped')
    ...

This lets you provision and deploy in one click from the GitHub Actions UI when setting up a brand-new server.

7. Local CI/CD Testing (Advanced)

Test your GitHub Actions workflow locally using nektos/act and a local Hylius mock VPS.

Start a mock VPS

bashdocker run -d --name mock-vps -p 2222:22 \
  alpine sh -c "apk add --no-cache openssh-server && \
  ssh-keygen -A && \
  echo 'root:password' | chpasswd && \
  /usr/sbin/sshd -D"

Run the workflow with act

bashact push \
  -W .github/workflows/hylius-deploy.yml \
  --secret HYLIUS_HOST=127.0.0.1 \
  --secret HYLIUS_PORT=2222 \
  --secret HYLIUS_USER=root \
  --secret HYLIUS_PASSWORD=password \
  --secret HYLIUS_TARGET_PATH=/var/www/my-app \
  --secret HYLIUS_REPO_URL=https://github.com/your-org/your-repo.git

🛡️ Security Best Practices

• Use SSH keys over passwords whenever possible
• Never commit your .env file — set secrets through the GitHub Secrets UI
• Secrets are passed as environment variables and are never logged in plain text
• The Dagger pipeline uses GITHUB_TOKEN (automatically provided) for GHCR auth — no personal token needed
• Hylius's headless mode is designed around GitHub's encrypted secrets — not plain-text environment files