# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://operations-project.gitbook.io/operations-experience-project/operations-site-server.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.