PHPackages operations/site-runner - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [DevOps & Deployment](/categories/devops) 4. / 5. operations/site-runner ActiveLibrary[DevOps & Deployment](/categories/devops) operations/site-runner ====================== Self-contained Continuous Delivery Site Hosting 0.1.0(1y ago)5457[4 issues](https://github.com/operations-project/ansible-collection-site-runner/issues)[3 PRs](https://github.com/operations-project/ansible-collection-site-runner/pulls)MITJinjaCI passing Since May 21Pushed 4mo ago1 watchersCompare [ Source](https://github.com/operations-project/ansible-collection-site-runner)[ Packagist](https://packagist.org/packages/operations/site-runner)[ Docs](https://github.com/operations-project/site-runner)[ RSS](/packages/operations-site-runner/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependenciesVersions (16)Used By (0) Operations Site Runner Ansible Collection ========================================= [](#operations-site-runner-ansible-collection) Server config for launching site runners from your codebase. ------------------------------------------------------------ [](#server-config-for-launching-site-runners-from-your-codebase) [![License](https://camo.githubusercontent.com/48ec640df7aa98ffef21cc458ad62f485e8c6afaab5ab4da8d13d84e1cd7779e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d3430383637372e737667)](LICENSE) This code sets up a server for launching and testing websites using GitOps tools like GitHub Actions and hosting tools like DDEV. The goal is to quickly launch running environments on any server for automated and manual testing, integrated directly with GitOps APIs. It uses GitHub Actions and Workflows with self-hosted runners, providing persistent, accessible environments and logs, fully integrated with GitHub Deployments & Checks APIs for optimal developer experience. For more details see ### What this does [](#what-this-does) This Ansible playbook prepares a bare linux server for running websites: 1. Creates users for administrators and grants SSH access using GitHub user SSH keys. 2. Installs Docker, Composer, & DDEV. 3. Creates a `platform` user for storing site code and running tasks. 4. Installs GitHub Self-hosted Runner as a service, running as `platform` user. 5. Listens for new jobs remotely. No need to grant GitHub access to post webhooks. 6. Runs the GitHub Actions as defined in the project's `.github/workflows` config. Then, the project's codebase takes over using GitHub Actions config. ### GitHub Actions [](#github-actions) With a self-hosted runner, all activity on the servers is run with GitHub's Actions system. Through the GitHub interface you can track every deployment, test run, and cron job for pull request and live environments. #### Deployment Logic [](#deployment-logic) For now, all deployment logic is stored in the GitHub workflow config: - Where to clone code. - Command to launch sites. - Command to run updates. - Command to sync data. See examples folder for working config. With the right GitHub Actions config, the server will: 1. Clone code to `/var/platform/example.com/pr#`. 2. Write special DDEV config to set unique URLs for each DDEV site. 3. Launch the site. (`ddev start`) 4. If a test site, sync data and run tests. For now, you must copy these templates into your workflows. As the project progresses, we will release shared tooling. Documentation ------------- [](#documentation) This is a very young project still in the proof of concept phase. More information will be added when possible. ### Architecture [](#architecture) 1. **Operations Platform** (This repository) - An Ansible Collection. Set of roles and configuration for bootstrapping a server to run sites. - Installed to `/usr/share/operations`. - Ansible Playbook: - `geerlingguy.security` - `geerlingguy.github-users` - `geerlingguy.composer` - `geerlingguy.docker` - Installs system users, Docker, Composer, GitHub Runner, & DDEV. (More engines TBD) - @TODO: Self-updating: Control User GitHub runner updates this repo and kicks off playbook when new commits are pushed for changing server config. - **Users:** - Special users are created to manage the server. - Control user (`control`) is for server updates. It has `sudo NOPASSWD` permissions to allow self-configuration. If using multiple servers, this user will have SSH access to those servers in order to configure them remotely. - Platform user (`platform`) is used for all app code. All apps are cloned into the home directory, `/var/platform`. The `platform` user has SSH access to clone repositories and access remote servers. The `platform` user runs the commands needed to launch sites, such as `ddev`. - System Administrators can be set by adding their GitHub username to the ansible variable `operations_admin_users`. Each user will be granted server access via the SSH keys uploaded to GitHub.com, and `sudo NOPASSWD` permissions to allow manual maintenance of the server. - **Service Engines** - Operations platform relies on other tools for launching sites. - "Service Engines" will make it simple to plug in any desired tooling to start, stop, destroy, and restore/sync sites by simply wrapping the tool's commands. - DDEV is used as the first service engine as a proof of concept. - More will be added whenever time allows. 2. **Git Runners** - This role installs and configures private Git Runners. - All needed operations are run through the Git host's "Workflows" or "Pipelines" system, including deployments, cron jobs, backups, etc. - Runners listen for events like git pushes or issue creation and then take the actions defined by the git-ops configuration files, without webhooks. This allows privately hosted servers to run sites without forcing users to grant access to the internet. - All tasks are logged in the web interfaces of the git hosts. No other task runner (such as jenkins) is needed. - Runner Documentation - [GitHub](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners) - [BitBucket](https://support.atlassian.com/bitbucket-cloud/docs/runners/) @TODO - [GitLab](https://docs.gitlab.com/runner/) @TODO 3. **Git Runner config** - Each project must contain workflow/pipeline configuration files specifically for that git host that works with the private runners. - Example config files are located in the (Templates)\[./templates\] folder (Coming soon). ### Links [](#links) - [GitHub issue templates](https://github.com/operations-project/site-runner/issues/templates/edit) - [GitHub pull request template](/.github/pull_request_template.md) - [Contributing guide](/CONTRIBUTING) (Decide about your code of conduct) TBD Getting Started --------------- [](#getting-started) This repo contains everything needed to set up an automated hosting platform. ### Prerequisites [](#prerequisites) 1. git 2. ansible Once the repo is cloned, ansible will set up the rest. ### Installing [](#installing) 1. Install Ansible & git. 2. Clone. ``` git clone git@github.com:operations-project/site-runner.git /usr/share/operations ``` 3. Prepare. This playbook creates GitHub runners automatically using a GitHub Token. This token is only used to create a runner. No other API interaction is needed because it is all handled by the GitHub Runners. Runner tasks get a unique `GITHUB_TOKEN` for every job, so users can interact with the GitHub API that way. *NOTE:* If your project is not a personal repo, you need to enable "Personal Access Tokens" in your organization. #### To enable Personal Access Tokens for organizations: [](#to-enable-personal-access-tokens-for-organizations) 1. Open your organization's page. For example: 2. Click *Settings*. 3. Click *Personal Access Tokens* in the left sidebar. 4. Go through the wizard to configure how tokens work in your organization. Once complete, your organization will be available when you create your own "Personal Access Token". #### To create Personal Access Tokens: [](#to-create-personal-access-tokens) 1. Go to the Create Token Page: 2. Under *Resource owner*, select your organization. 3. Under *Repository Permissions*, for *Administration*, select *Read/Write*. 4. Click *Generate Token*. Save the token for the **Configure** step, below. 4. Configure Ansible Inventory. Ansible inventory is very powerful and flexible. There are many ways to manage your inventory. This playbook comes with example inventory and variable files that you can use to manually place in `/etc/ansible/hosts` and `/etc/ansible/host_vars/sites.myhost.com.yml` See example files in [`./ansible/hosts.example`](./ansible/hosts.example) and [`./ansible/host_vars/host.example.yml`](./ansible/host_vars/host.example.yml) The result should look something like this: - `/etc/ansible/hosts` ``` [operations_host_ddev] sites.myhost.com ansible_connection=local ``` - `/etc/ansible/host_vars/sites.myhost.com.yml` ``` # Add a list of github usernames to grant access to. They will get sudo users and SSH access. operations_admin_users: - YOUR_GITHUB_USERNAME operations_github_api_token: YOUR_API_TOKEN operations_github_runners: - repo_name: YOUR_ORG/YOUR_REPO ``` For details on additional options, see [`./ansible/host_vars/host.example.yml`](./ansible/host_vars/host.example.yml). You are free to build up your ansible inventory as you see fit. These are the essential options. 5. Install. To install, run `ansible-playbook` as your user (not with `sudo`). Ansible knows how to run `sudo` for the steps that require it. As long as your active user *can* sudo, you can run `ansible-playbook` as your personal user account. ``` ansible-playbook /usr/share/operations/playbook.yml ``` Once the playbook completes successfully, you will have a new runner present in GitHub. To confirm: - Visit your repository's *Settings* page. - Click *Actions*, then *Runners*. - You should see a runner that matches the hostname and labels you set in your ansible inventory > *NOTE:* The playbook will create users from your `operations_admin_users` variables, and will grant them passwordless `SUDO` access. After running it the first time, you can run `ansible-playbook` as your personal user. 6. Implement. To use it, you need to add a GitHub workflow config file that has `runs-on` set to a label that your runner has. An example to confirm the runner: ``` # .github/workflows/demo.yml name: Verify Self-Hosted Runner # Run on all pushes and manual triggering with "workflow_dispatch" on: workflow_dispatch: push: jobs: verify: # Match a label or use the hostname label. runs-on: sites.myhost.com steps: - name: Environment run: | hostname -f whoami env ``` More workflow samples coming soon. Built With ---------- [](#built-with) List significant dependencies that developers of this project will interact with. - [Composer](https://getcomposer.org/) - Dependency Management - [Robo](https://robo.li/) - PHP Task Runner - [Symfony](https://symfony.com/) - PHP Framework - [Ansible](https://ansible.com) - System Configuration Platform Contributing ------------ [](#contributing) Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on the process for submitting pull requests to us. Versioning ---------- [](#versioning) We use [SemVer](http://semver.org/) for versioning. For the versions available, see the [releases](https://github.com/operations-project/site-runner/releases) page. Authors ------- [](#authors) - **Jon Pugh** - created project from template. See also the list of [contributors](https://github.com/operations-project/site-runner/contributors) who participated in this project. License ------- [](#license) This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details Acknowledgments --------------- [](#acknowledgments) - @g1a for all that you do. - aegir, lando, docksal, ddev, etc ### Health Score 27 — LowBetter than 49% of packages Maintenance39 Infrequent updates — may be unmaintained Popularity17 Limited adoption so far Community7 Small or concentrated contributor base Maturity38 Early-stage or recently created project Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 727d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/10539fb9e887c35b626eba70c97dd9d53ba14e987d4f129b55a488664a834eca?d=identicon)[jonpugh](/maintainers/jonpugh) --- Top Contributors [![jonpugh](https://avatars.githubusercontent.com/u/106420?v=4)](https://github.com/jonpugh "jonpugh (110 commits)") ### Embed Badge ![Health badge](/badges/operations-site-runner/health.svg) ``` [![Health](https://phpackages.com/badges/operations-site-runner/health.svg)](https://phpackages.com/packages/operations-site-runner) ``` ### Alternatives [deployer/deployer Deployment Tool 11.0k25.4M207](/packages/deployer-deployer)[appwrite/server-ce End to end backend server for frontend and mobile apps. 55.3k84.2k](/packages/appwrite-server-ce)[pragmarx/health Laravel Server & App Health Monitor and Notifier 2.0k1.0M2](/packages/pragmarx-health)[felixfbecker/language-server-protocol PHP classes for the Language Server Protocol 22476.7M6](/packages/felixfbecker-language-server-protocol)[heroku/heroku-buildpack-php Toolkit for starting a PHP application locally, with or without foreman, using the same config for PHP and Apache2/Nginx as on Heroku 8161.3M10](/packages/heroku-heroku-buildpack-php)[tiamo/phpas2 PHPAS2 is a php-based implementation of the EDIINT AS2 standard 4674.7k](/packages/tiamo-phpas2) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)