{"id":21702894,"url":"https://github.com/operations-project/ansible-collection-site-runner","last_synced_at":"2025-03-20T16:32:45.838Z","repository":{"id":228996245,"uuid":"775474245","full_name":"operations-project/ansible-collection-site-runner","owner":"operations-project","description":"Ansible collection to install GitHub site runners and DDEV.","archived":false,"fork":false,"pushed_at":"2025-02-20T14:38:58.000Z","size":209,"stargazers_count":5,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-20T15:34:32.554Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Dockerfile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/operations-project.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-03-21T13:08:30.000Z","updated_at":"2025-02-20T14:39:03.000Z","dependencies_parsed_at":"2025-01-25T15:26:05.880Z","dependency_job_id":"af701e6e-a460-4891-a201-56e8ce8a087d","html_url":"https://github.com/operations-project/ansible-collection-site-runner","commit_stats":null,"previous_names":["jonpugh/ash-ops","operations-platform/site-server","operations-project/site-runner","operations-project/site-server","operations-project/ansible-collection-site-runner"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/operations-project%2Fansible-collection-site-runner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/operations-project%2Fansible-collection-site-runner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/operations-project%2Fansible-collection-site-runner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/operations-project%2Fansible-collection-site-runner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/operations-project","download_url":"https://codeload.github.com/operations-project/ansible-collection-site-runner/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244649664,"owners_count":20487465,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-25T21:22:00.141Z","updated_at":"2025-03-20T16:32:45.813Z","avatar_url":"https://github.com/operations-project.png","language":"Dockerfile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Operations Site Runner Ansible Collection\n\n## Server config for launching site runners from your codebase.\n\n[![License](https://img.shields.io/badge/license-MIT-408677.svg)](LICENSE)\n\n\u003c!--\nThere are two choices for LICENSE badges:\n\n1. License using shields.io (above): Can contain any text you want, and has no prerequisites, but must be manually updated if you change the license.\n2. License using poser.pugx.org (below): shows the license that Packagist.org read from your composer.json file. Must register with Packagist to use Poser.\n\n[![License](https://poser.pugx.org/operations-project/site-runner)](https://github.com/operations-project/site-runner//main/LICENSE)\n--\u003e\n\nThis code sets up a server for launching and testing websites using GitOps tools like GitHub Actions and hosting tools like DDEV.\n\nThe goal is to quickly launch running environments on any server for automated and manual testing, integrated directly with GitOps APIs.\n\nIt uses GitHub Actions and Workflows with self-hosted runners, providing persistent, accessible environments and logs, fully integrated with GitHub Deployments \u0026 Checks APIs for optimal developer experience.\n\nFor more details see https://operations-project.gitbook.io/operations-experience-project/operations-site-server \n\n### What this does\n\nThis Ansible playbook prepares a bare linux server for running websites:\n\n1. Creates users for administrators and grants SSH access using GitHub user SSH keys.\n2. Installs Docker, Composer, \u0026 DDEV.\n3. Creates a `platform` user for storing site code and running tasks.\n4. Installs GitHub Self-hosted Runner as a service, running as `platform` user.\n5. Listens for new jobs remotely. No need to grant GitHub access to post webhooks.\n6. Runs the GitHub Actions as defined in the project's `.github/workflows` config.\n\nThen, the project's codebase takes over using GitHub Actions config.\n\n### GitHub Actions\n\nWith a self-hosted runner, all activity on the servers is run with GitHub's Actions system.\n\nThrough the GitHub interface you can track every deployment, test run, and cron job for pull request and live environments.\n\n#### Deployment Logic\n\nFor now, all deployment logic is stored in the GitHub workflow config:\n\n- Where to clone code.\n- Command to launch sites.\n- Command to run updates.\n- Command to sync data.\n\nSee examples folder for working config.\n\nWith the right GitHub Actions config, the server will:\n\n1. Clone code to `/var/platform/example.com/pr#`.\n2. Write special DDEV config to set unique URLs for each DDEV site.\n3. Launch the site. (`ddev start`)\n4. If a test site, sync data and run tests.\n\nFor now, you must copy these templates into your workflows. As the project progresses, we will release shared tooling.\n\n## Documentation\n\nThis is a very young project still in the proof of concept phase. More information will be added when possible.\n\n### Architecture\n\n1. **Operations Platform** (This repository)\n    - An Ansible Collection. Set of roles and configuration for bootstrapping a server to run sites.\n    - Installed to `/usr/share/operations`.\n    - Ansible Playbook:\n      - `geerlingguy.security`\n      - `geerlingguy.github-users`\n      - `geerlingguy.composer`\n      - `geerlingguy.docker`\n    - Installs system users, Docker, Composer, GitHub Runner, \u0026 DDEV. (More engines TBD)\n    - @TODO: Self-updating: Control User GitHub runner updates this repo and kicks off playbook when new commits are pushed for changing server config.\n    - **Users:**\n      - Special users are created to manage the server.\n      - 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.\n      - 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`.\n      - 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.\n    - **Service Engines**\n      - Operations platform relies on other tools for launching sites.\n      - \"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.\n      - DDEV is used as the first service engine as a proof of concept.\n      - More will be added whenever time allows.\n\n2. **Git Runners**\n    - This role installs and configures private Git Runners.\n    - All needed operations are run through the Git host's \"Workflows\" or \"Pipelines\" system, including deployments, cron jobs, backups, etc.\n    - 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.\n    - All tasks are logged in the web interfaces of the git hosts. No other task runner (such as jenkins) is needed.\n    - Runner Documentation\n        - [GitHub](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners)\n        - [BitBucket](https://support.atlassian.com/bitbucket-cloud/docs/runners/) @TODO\n        - [GitLab](https://docs.gitlab.com/runner/) @TODO\n3. **Git Runner config**\n    - Each project must contain workflow/pipeline configuration files specifically for that git host that works with the private runners.\n    - Example config files are located in the (Templates)[./templates] folder (Coming soon).\n\n\n### Links\n\n- [GitHub issue templates](https://github.com/operations-project/site-runner/issues/templates/edit)\n- [GitHub pull request template](/.github/pull_request_template.md)\n- [Contributing guide](/CONTRIBUTING) (Decide about your code of conduct)\n\nTBD\n\n## Getting Started\n\nThis repo contains everything needed to set up an automated hosting platform.\n\n### Prerequisites\n\n1. git\n2. ansible\n\nOnce the repo is cloned, ansible will set up the rest.\n\n### Installing\n\n0. Install Ansible \u0026 git.\n\n1. Clone.\n\n        git clone git@github.com:operations-project/site-runner.git /usr/share/operations\n\n2. Prepare.\n\n    This playbook creates GitHub runners automatically using a GitHub Token.\n\n    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.\n\n   *NOTE:* If your project is not a personal repo, you need to enable \"Personal Access Tokens\" in your organization.\n\n    #### To enable Personal Access Tokens for organizations:\n\n    1. Open your organization's page. For example: https://github.com/organizations/operations-platform/\n    2. Click *Settings*.\n    3. Click *Personal Access Tokens* in the left sidebar.\n    4. Go through the wizard to configure how tokens work in your organization.\n\n    Once complete, your organization will be available when you create your own \"Personal Access Token\".\n\n    #### To create Personal Access Tokens:\n\n    1. Go to the Create Token Page: https://github.com/settings/personal-access-tokens/new\n    2. Under *Resource owner*, select your organization.\n    3. Under *Repository Permissions*, for *Administration*, select *Read/Write*.\n    4. Click *Generate Token*. Save the token for the **Configure** step, below.\n\n3. Configure Ansible Inventory.\n\n    Ansible inventory is very powerful and flexible. There are many ways to manage your inventory.\n\n    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`\n\n    See example files in [`./ansible/hosts.example`](./ansible/hosts.example) and [`./ansible/host_vars/host.example.yml`](./ansible/host_vars/host.example.yml)\n\n    The result should look something like this:\n\n    * `/etc/ansible/hosts`\n\n          [operations_host_ddev]\n          sites.myhost.com ansible_connection=local\n\n    * `/etc/ansible/host_vars/sites.myhost.com.yml`\n\n          # Add a list of github usernames to grant access to. They will get sudo users and SSH access.\n          operations_admin_users:\n          - YOUR_GITHUB_USERNAME\n\n          operations_github_api_token: YOUR_API_TOKEN\n          operations_github_runners:\n          - repo_name: YOUR_ORG/YOUR_REPO\n\n    For details on additional options, see [`./ansible/host_vars/host.example.yml`](./ansible/host_vars/host.example.yml).\n\n    You are free to build up your ansible inventory as you see fit. These are the essential options.\n\n4. Install.\n\n    To install, run `ansible-playbook` as your user (not with `sudo`). Ansible knows how to run `sudo` for the steps that require it.\n\n    As long as your active user *can* sudo, you can run `ansible-playbook` as your personal user account.\n\n        ansible-playbook /usr/share/operations/playbook.yml\n\n   Once the playbook completes successfully, you will have a new runner present in GitHub. To confirm:\n\n    * Visit your repository's *Settings* page.\n    * Click *Actions*, then *Runners*.\n    * You should see a runner that matches the hostname and labels you set in your ansible inventory\n\n    \u003e *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.\n\n5. Implement.\n\n    To use it, you need to add a GitHub workflow config file that has `runs-on` set to a label that your runner has.\n\n    An example to confirm the runner:\n\n    ```yaml\n    # .github/workflows/demo.yml\n    name: Verify Self-Hosted Runner\n\n    # Run on all pushes and manual triggering with \"workflow_dispatch\"\n    on:\n        workflow_dispatch:\n        push:\n\n    jobs:\n      verify:\n        # Match a label or use the hostname label.\n        runs-on: sites.myhost.com\n\n        steps:\n          - name: Environment\n            run: |\n              hostname -f\n              whoami\n              env\n    ```\n\n    More workflow samples coming soon.\n\n## Built With\n\nList significant dependencies that developers of this project will interact with.\n\n* [Composer](https://getcomposer.org/) - Dependency Management\n* [Robo](https://robo.li/) - PHP Task Runner\n* [Symfony](https://symfony.com/) - PHP Framework\n* [Ansible](https://ansible.com) - System Configuration Platform\n\n## Contributing\n\nPlease read [CONTRIBUTING.md](CONTRIBUTING.md) for details on the process for submitting pull requests to us.\n\n## Versioning\n\nWe use [SemVer](http://semver.org/) for versioning. For the versions available, see the [releases](https://github.com/operations-project/site-runner/releases) page.\n\n## Authors\n\n* **Jon Pugh** - created project from template.\n\nSee also the list of [contributors](https://github.com/operations-project/site-runner/contributors) who participated in this project.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details\n\n## Acknowledgments\n\n* @g1a for all that you do.\n* aegir, lando, docksal, ddev, etc\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foperations-project%2Fansible-collection-site-runner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foperations-project%2Fansible-collection-site-runner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foperations-project%2Fansible-collection-site-runner/lists"}