# Site Runner

GitHub workflows for private self-hosted hosting and testing environments.

{% embed url="<https://github.com/operations-project/site-runner-ddev>" %}
GitHub Action for launching DDEV sites.
{% endembed %}

{% embed url="<https://github.com/operations-project/site-runner/>" %}
Ansible role for preparing a server for running sites.
{% endembed %}

## Features

### DDEV powered sites on the internet

<figure><img src="https://3263112067-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwthQiMw8fixu3bEHTo5u%2Fuploads%2F8hf03CpTZpEGh69G1NoB%2Fimage.png?alt=media&#x26;token=cbb95a4e-3fd2-480e-9484-a01df5ef898b" alt=""><figcaption><p>The <code>ddev list</code> command run on an Operations Site Server.</p></figcaption></figure>

### GitHub Actions for everything

<figure><img src="https://3263112067-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwthQiMw8fixu3bEHTo5u%2Fuploads%2FtQAuMm1WupSqLgcQxzao%2Fimage.png?alt=media&#x26;token=8146f41e-eac3-4666-8a11-296b6ee20ee5" alt=""><figcaption><p>GitHub Repository Actions interface.</p></figcaption></figure>

<figure><img src="https://3263112067-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwthQiMw8fixu3bEHTo5u%2Fuploads%2FL9LPoQtZ2h6UPrum6wUs%2Fimage.png?alt=media&#x26;token=f67c3364-b2bb-46af-abd8-24890ed68079" alt=""><figcaption><p>Deployment task running from private server in GitHub UI.</p></figcaption></figure>

### Cron runs

Gain transparency into your cron process by using scheduled GitHub actions.

<figure><img src="https://3263112067-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwthQiMw8fixu3bEHTo5u%2Fuploads%2FqvPxRmiWD4GC3nUI33ho%2Fimage.png?alt=media&#x26;token=6ba9c0f3-b963-4b56-a613-efbc53502b66" alt=""><figcaption><p>Cron runs brought to you by: GitHub Actions!</p></figcaption></figure>

### Pull Request & Deployments Integration

<figure><img src="https://3263112067-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwthQiMw8fixu3bEHTo5u%2Fuploads%2FwpyRQHY7RBnN2L27MXE1%2Fimage.png?alt=media&#x26;token=f04f5fcf-1609-4733-813f-4070e1ca7f1d" alt=""><figcaption><p>Use the GitHub interface for quickly making changes and submitting a pull request</p></figcaption></figure>

<figure><img src="https://3263112067-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwthQiMw8fixu3bEHTo5u%2Fuploads%2FzAgSV76Pb2zWvEllISO9%2Fimage.png?alt=media&#x26;token=0647aa61-9292-423c-9aa0-4a4fa3210a16" alt=""><figcaption><p>GitHub users get real-time feedback on the deployment of their code.</p></figcaption></figure>

<figure><img src="https://3263112067-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwthQiMw8fixu3bEHTo5u%2Fuploads%2FXTTg4xZPqj1sTgaX63pP%2Fimage.png?alt=media&#x26;token=b9d33bdc-1fba-4d96-9a8e-f05096df8f40" alt=""><figcaption><p>Immediate and direct access to easy-to-read logs, with links to running sites.</p></figcaption></figure>

<figure><img src="https://3263112067-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwthQiMw8fixu3bEHTo5u%2Fuploads%2FBJLz0CFiGHEaHqz9tTn5%2Fimage.png?alt=media&#x26;token=0e4369e2-f746-47a8-8bc9-24797d4a93b9" alt=""><figcaption><p>GitHub Pull Requests with Commit Checks and Deployments API integration. "View Deployment" is a direct link to the site</p></figcaption></figure>

### Environments & Deployments

By using GitHub Workflows, integration with Commit Statuses, Deployment API, and Environments is seamless. No custom code, no API integration.

<figure><img src="https://3263112067-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwthQiMw8fixu3bEHTo5u%2Fuploads%2FxcdqWlqzMq5esprdmach%2Fimage.png?alt=media&#x26;token=e6627f50-70dd-4c3a-a5f2-9b6e1b029db5" alt=""><figcaption><p>GitHub's Environment interface shows every deployment to every environment.</p></figcaption></figure>

### Secrets

Store all sensitive info in GitHub repository secrets. Allows users to replace values when needed, such as for custom HTTPS certificates.

<figure><img src="https://3263112067-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwthQiMw8fixu3bEHTo5u%2Fuploads%2FaW2ckWOpytVhaDfFObNC%2Fimage.png?alt=media&#x26;token=37f57db0-83c2-4235-bd55-31608dca550f" alt=""><figcaption></figcaption></figure>

## Examples

### Continuously Deploy `main` branch to a live site.

```yaml
# ./github/workflows/deploy.yml
name: Deploy to live
on:
  push:
    branches:
      - main
jobs:
  build:
    name: Deploy site
    runs-on: yourserver.com
    environment:
      name: "live"
      url: "http://www.yoursite.com?${{ github.run_id }}"
    steps:
    - uses: operations-project/site-runner-ddev@main
      with:
        path: projects/yoursite.com/live
        git-reference: main
        ddev-fqdns: yoursite.com,live.yoursite.com
```

### Deploy Preview Environments

```yaml
# ./github/workflows/pull-request-environment.yml
name: Deploy to Preview
on: [pull_request]
jobs:
  build:
    name: Deploy Site
    runs-on: yourserver.com
    environment:
      name: "pr${{ github.event.number }}"
      url: "http://pr${{ github.event.number }}.ci.yoursite.com?${{ github.run_id }}"
    steps:
    - uses: operations-project/site-runner-ddev@main
      with:
        sync: yes
        ddev-project-tld: ci.yoursite.com
        ddev-project-name: pr${{ github.event.number }}
```

### Delete Preview Environment

```yaml
name: Delete Pull Request Environment

on:
  pull_request:
    types:
      - closed

env:
  DDEV_PROJECT_PATH_FULL: "/var/platform/Sites/${{ github.repository }}/pr${{ github.event.number }}"
  
jobs:
  delete:
    name: Delete Environment
    runs-on: yourserver.com

    steps:
      - name: Remove site
        working-directory: ${{ env.DDEV_PROJECT_PATH_FULL }}
        run: |
          ddev remove --remove-data --omit-snapshot

      - name: Remove code
        working-directory: ${{ env.DDEV_PROJECT_PATH_FULL }}
        run: |
          rm -rf ${{ env.DDEV_PROJECT_PATH_FULL }}
```

### Run Cron

```yaml
name: Drupal Cron
on:
  schedule:
    - cron: '45 * * * *'

jobs:
  cron:
    name: Drupal Cron
    runs-on: yourserver.com
    steps:    
      - name: Run cron
        working-directory: projects/yoursite.com/live
        run: |
          ddev drush cron -v
          ddev drush status
```

## Server Install

The repo contains Ansible roles to prepare a server for running sites like this:

1. Users.
   * Configures users from GitHub usernames with Sudo and SSH access.
   * Creates a `platform` user for cloning code, running jobs, and launching sites.
2. DDEV.
   1. Installs and configures DDEV for "casual hosting".
3. GitHub Runners
   1. Installs and configures GitHub runners as a service.

Once installed, your server is ready to react to git pushes, running jobs from GitHub workflow config files as the `platform` user.

With the right GitHub workflow config, PREs will be automatically created for Pull Requests, and environments can be created manually.