Deploying Kirby with DeployHQ

Introduction

A major advantage of using a CMS like Kirby is the ability to deploy your website directly from a Git repository. Since Kirby uses flat files instead of a database, this includes both your code and content.

Using DeployHQ, you can automatically deploy changes whenever you push code to your repository, making it easy to maintain both staging and production environments. This tutorial will walk you through setting up a complete deployment workflow.

Prerequisites

• Basic understanding of Git and source control
• Web hosting with SSH support
• Basic knowledge of web administration and terminal usage
• A DeployHQ account (free tier available)

Note about Kirby Licensing

A Kirby license isn't required for development or staging sites, but you'll need to purchase one before deploying to production. See the Kirby License for details.

Creating a New Kirby Project

Using the Starter Kit

# Clone the starter repository
git clone https://github.com/christattum/kirby-starter-vanilla.git your-project-name
cd your-project-name
rm -rf .git

Setting Up Local Development

If you're using DDEV:

1- Edit .ddev/config.yaml:

name: your-project-name
type: php
docroot: ""
php_version: "8.2"

2- Start the environment:

ddev start
ddev composer install
ddev launch

Alternatively, for MAMP/WAMP/Laravel Herd:

composer install

Setting Up Version Control

Creating a New Repository

1- Initialize Git:

git init
git add .
git commit -m "Initial commit"

2- Create a new repository on GitHub/GitLab/Bitbucket

3- Push your code:

git remote add origin your-repository-url
git push -u origin main

Server Configuration

Creating a Staging Environment

1- Set up a subdomain:

staging.yourdomain.com

2- Protect the staging site with password protection through your hosting panel

SSH Configuration

Creating SSH Keys for Your Local Machine

cd ~/.ssh
ssh-keygen -t ed25519 -a 200 -f your-machine-name -C "your-machine-name"

Add to your ~/.ssh/config:

Host staging-site
    HostName your-server-hostname
    IdentityFile ~/.ssh/your-machine-name
    Port your-ssh-port
    User your-ssh-user

Test the connection:

ssh staging-site

Setting Up DeployHQ

Creating a Project

1. Sign up at DeployHQ
2. Click "New Project"
3. Select your repository provider
4. Choose your repository
5. Name your project

Configuring Deployment Settings

1. Navigate to "Servers & Groups"
2. Click "New Server"
3. Enter server details:

Name: Staging
Protocol: SFTP/SSH
Hostname: your-server-hostname
Port: your-ssh-port
Username: your-ssh-user
Authentication: Public key
Deploy Path: /path/to/public_html

SSH Key Configuration

1. Copy DeployHQ's public key from the server configuration
2. Add to your server's ~/.ssh/authorized_keys

Repository Configuration

Create .deploybuild.yaml in your repository:

build_languages:
  - name: "node"
    version: "18"
  - name: "php"
    version: "8.0"

build_commands:
  - description: "Install NPM Dependencies"
    command: "npm install \n npm run build"
    halt_on_error: true
  - description: "Install Composer Dependencies"
    command: "composer install --no-dev"
    halt_on_error: true

build_cache_files:
  - path: node_modules/**

Also, in the SSH Commands, you can configure the following hooks:

# pre_deploy_commands:
php artisan down

# post_deploy_commands:
php artisan cache:clear
php artisan up

Initial Repository Setup on Server

SSH into your server:

ssh staging-site
cd /path/to/public_html
git clone your-repository-url .
composer install

Configuring Automatic Deployments

1. In DeployHQ, go to "Automatic Deployments"
2. Enable automatic deployments
3. Select your branch (e.g., "main")
4. Choose your server

Environment Configuration

1. Go to "Config Files"
2. Create .env:

KIRBY_DEBUG=false
KIRBY_PANEL_INSTALL=false

Testing the Deployment

1. Make a local change:

# Edit content/home.txt
git add content/home.txt
git commit -m "Update home content"
git push origin main

1. Monitor the deployment in DeployHQ's dashboard

Advanced Configuration

Automatic Deployments

1. Go to "Automatic Deployments" inside your project settings
2. Use for webhook integration:

curl -X POST https://your-account.deployhq.com/deploy/your-project/your-token

Deployment Notifications

Set up in "Notifications": - Email notifications - Slack integration - Discord webhooks

Multiple Environments

1. Create additional server groups for different environments
2. Configure branch-specific deployments:
   • main → staging
   • production → live site

Best Practices

1. Always test on staging first
2. Use meaningful commit messages
3. Keep sensitive data in environment variables
4. Regular backups before major deployments

Troubleshooting

Common issues and solutions:

1. Permission errors:

chmod -R 755 public_html
chown -R www-data:www-data public_html

1. Deployment failures:
2. Check SSH connectivity
3. Verify DeployHQ hooks
4. Review server logs

Summary

You now have:

• Automated deployments via DeployHQ
• Staging environment setup
• Version-controlled Kirby site
• Secure SSH configuration

Next steps:

1. Set up production environment
2. Configure additional security measures
3. Implement backup strategy
4. Add monitoring tools

Remember to purchase a Kirby license before going live with your production site.

This completes the basic setup for deploying Kirby with DeployHQ. For production deployments, consider adding additional security measures and monitoring tools.