> For the complete documentation index, see [llms.txt](https://operations-project.gitbook.io/operations-experience-project/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://operations-project.gitbook.io/operations-experience-project/operations-site-server.md).

# 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="/files/2sAzs2Zpfdy4yK0tueMf" 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="/files/JDDDgV6r4VhafqgpIp2K" alt=""><figcaption><p>GitHub Repository Actions interface.</p></figcaption></figure>

<figure><img src="/files/JCgRAnY3IueFlAeLS90S" 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="/files/NYuUSS39uWKTVmxO3BWx" alt=""><figcaption><p>Cron runs brought to you by: GitHub Actions!</p></figcaption></figure>

### Pull Request & Deployments Integration

<figure><img src="/files/NtJ4lLeCE5AyVfiPc9AL" alt=""><figcaption><p>Use the GitHub interface for quickly making changes and submitting a pull request</p></figcaption></figure>

<figure><img src="/files/iiTjepBQloKCMRWjgA1Z" alt=""><figcaption><p>GitHub users get real-time feedback on the deployment of their code.</p></figcaption></figure>

<figure><img src="/files/qjWzofn1RiTlPRX2EmjS" alt=""><figcaption><p>Immediate and direct access to easy-to-read logs, with links to running sites.</p></figcaption></figure>

<figure><img src="/files/JuHZlzzSkkttr7DojwLg" 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="/files/lgLNqzKTT9gSFE6tFWVp" 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="/files/P3xIRWUSuIXAc01QtJ5H" 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.