## Introduction

A major advantage of using a CMS like [Kirby](https://getkirby.com/) 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](https://www.deployhq.com), 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](https://www.deployhq.com) 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](https://getkirby.com/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](https://www.deployhq.com/guides/ddev-local-development):

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](https://www.deployhq.com)
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](https://www.deployhq.com), 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](https://www.deployhq.com) hooks
4. Review server logs

## Summary

You now have:

- Automated deployments via [DeployHQ](https://www.deployhq.com)
- 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](https://www.deployhq.com). For production deployments, consider adding additional security measures and monitoring tools.