Rename to operations-platform/site-server

.github/workflows/ci.yml

@@ -14,17 +14,11 @@ jobs:
 
     runs-on: ubuntu-latest
 
-    env:
-
-      PHP_EXTENSIONS: dom, json, libxml, mbstring, pdo_sqlite, soap, xml, xmlwriter
-
     steps:
       - uses: actions/checkout@v3
         with:
           show-progress: false
 
-      - uses: php-actions/composer@v6
-
       - name: Install docker-compose
         uses: KengoTODA/actions-setup-docker-compose@v1
         with:
@@ -39,36 +33,43 @@ jobs:
       - name: Set runner name
         if: github.event_name != 'pull_request'
         run: |
-          echo "ASH_NAME=${{ github.ref_name }}" >> "$GITHUB_ENV"
-          echo "ASH_ENVIRONMENT_NAME=ash.${{ github.ref_name }}.local.computer" >> "$GITHUB_ENV"
+          echo "OPERATIONS_NAME=${{ github.ref_name }}" >> "$GITHUB_ENV"
+          echo "OPERATIONS_ENVIRONMENT_NAME=operations.${{ github.ref_name }}.local.computer" >> "$GITHUB_ENV"
 
       - name: Set runner name
         if: github.event_name == 'pull_request'
         run: |
-          echo "ASH_NAME=pr${{ github.event.number }}" >> "$GITHUB_ENV"
-          echo "ASH_ENVIRONMENT_NAME=ash.pr${{ github.event.number }}.local.computer" >> "$GITHUB_ENV"
+          echo "OPERATIONS_NAME=pr${{ github.event.number }}" >> "$GITHUB_ENV"
+          echo "OPERATIONS_ENVIRONMENT_NAME=operations.pr${{ github.event.number }}.local.computer" >> "$GITHUB_ENV"
+
+      - name: Set ansible inventory hostname
+        run: |
+          echo "[operations_host_ddev]
+          ${{ env.OPERATIONS_ENVIRONMENT_NAME }} ansible_connection=local" > ./ansible/hosts
 
       - name: Set variables
         run: |
-          echo -e '[ash_host]\n${{ env.ASH_ENVIRONMENT_NAME }} ansible_connection=local' > ./ansible/hosts
-          echo "DOCKER_HOSTNAME=${{ env.ASH_ENVIRONMENT_NAME }}" > .env
+          echo "DOCKER_HOSTNAME=${{ env.OPERATIONS_ENVIRONMENT_NAME }}" > .env
           echo "# CI variables set!
-          ash_admin_users:
+          operations_github_api_token: ${{ secrets.OPERATIONS_GITHUB_API_TOKEN }}
+          operations_admin_users:
           - jonpugh
-          ash_github_runners:
-          - repo_url: ${{ github.server_url	}}/${{ github.repository }}
-            runner_token: ${{ secrets.RUNNER_TOKEN }}
-            runner_name:  ${{ env.ASH_ENVIRONMENT_NAME }}
+          operations_github_runners:
+          - repo_name: ${{ github.repository }}
+            runner_name:  ${{ env.OPERATIONS_ENVIRONMENT_NAME }}
             runner_labels: ci
             user: platform
-          " > ./ansible/host_vars/${{ env.ASH_ENVIRONMENT_NAME }}.yml
-          cat ./ansible/host_vars/${{ env.ASH_ENVIRONMENT_NAME }}.yml
+          " > ./ansible/host_vars/${{ env.OPERATIONS_ENVIRONMENT_NAME }}.yml
+          cat ./ansible/host_vars/${{ env.OPERATIONS_ENVIRONMENT_NAME }}.yml
+
+      - name: Install task CLI
+        run: ./scripts/install-task.sh
 
       - name: Build Platform
-        run: composer dev:start
+        run: bin/task start
 
       - name: Test Platform
         run: |
-          docker-compose exec -u platform ash whoami
-          docker-compose exec -u platform ash hostname
-          docker-compose exec -u platform ash ddev
+          docker-compose exec -u platform operations whoami
+          docker-compose exec -u platform operations hostname
+          docker-compose exec -u platform operations ddev

CHANGELOG.md

@@ -2,7 +2,17 @@
 
 ### Unreleased
 
-* TBD
+* Renamed to `operations-platform/site-server`.
+* Improved ansible inventory setup.
+* Added server roles for security, users, docker, ddev.
+* Added role to install GitHub Actions Runner.
+* Much improved README.md.
+* Finalized passing tests.
+* Added `Taskfile.yml` for developer tooling.
+
+@TODO:
+
+* Install as a service.
 
 ### 0.1.0 - 2024/Mar/21
 

CONTRIBUTING.md

@@ -1,6 +1,6 @@
-# Contributing to AshOps
+# Contributing to Operations Platform
 
-Thank you for your interest in contributing to AshOps! Here are some of the guidelines you should follow to make the most of your efforts:
+Thank you for your interest in contributing to Operations Platform! Here are some of the guidelines you should follow to make the most of your efforts:
 
 ## Code Style Guidelines
 

README.md

@@ -1,6 +1,6 @@
-# AshOps
+# Operations Platform Site Server
 
-Install stuff for creating an automation platform for websites using the Ash Cli and GitOps tools like GitHub Workflows and BitBucket Pipelines.
+## Simple self-hosted git-powered web app automation.
 
 [![License](https://img.shields.io/badge/license-MIT-408677.svg)](LICENSE)
 
@@ -10,55 +10,98 @@ There are two choices for LICENSE badges:
 1. 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.
 2. 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.
 
-[![License](https://poser.pugx.org/jonpugh/ash-ops/license)](https://github.com/jonpugh/ash-ops//master/LICENSE)
+[![License](https://poser.pugx.org/operations-platform/site-server)](https://github.com/operations-platform/site-server//main/LICENSE)
 -->
 
-More coming soon.
+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.
+
+### 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
+
+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
+
+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
 
-### Architecture Plan
+This is a very young project still in the proof of concept phase. More information will be added when possible.
 
-I am about to build this:
+### Architecture
 
-1. Ash Ops Repo. (This repository)
-    - Installed to `/usr/share/ash`, owned by `control`.
+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`
-    - Composer Dependencies like `jonpugh/ash`
-    - Installs Users, PHP, Composer, Docker, GitHub Runner, and Ash Cli.
-    - Can be replaced with a custom version to allow control over server config.
-    - Control User GitHub runner updates this repo and kicks off playbook when new commits are pushed.
-2. Task Runners
-    - App repo runners run as a service under `platform` user.
-    - Responsible for responding to git pushes, cloning code into environments, and starting services.
+    - 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
-5. Users
-    - Control user (`control`) has `sudo NOPASSWD` permissions to allow automation.
-    - Platform user (`platform`) has `docker` permissions only, plus SSH access to clone repositories and access remote servers.
-    - Admin users will all ssh in with their own usernames, and `sudo su` to `platform` or `control` as needed.
-2. Ash CLI
-    - Available at `/usr/share/ash/bin/ash`
-    - Runs under `platform` user.
-    - Site inventory.
-3. App repo.
-   - Website code.
-   - Runner config.
-4. Service CLI
-    - The thing that launches services for a site.
-    - Right now, it's DDEV.
-    - Runners clone the code, then run the service CLI commands as defined in runner config files.
+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
 
-- [GitHub issue templates](https://github.com/jonpugh/ash-ops/issues/templates/edit)
+- [GitHub issue templates](https://github.com/operations-platform/site-server/issues/templates/edit)
 - [GitHub pull request template](/.github/pull_request_template.md)
 - [Contributing guide](/CONTRIBUTING) (Decide about your code of conduct)
 
@@ -77,31 +120,37 @@ Once the repo is cloned, ansible will set up the rest.
 
 ### Installing
 
-0. Install Ansible.
+0. Install Ansible & git.
 
 1. Clone.
 
-        git clone [email protected]:jonpugh/ash-ops.git /usr/share/ash
+        git clone [email protected]:operations-platform/site-server.git /usr/share/operations
 
-2. Get a GitHub Runner token.
+2. Get a GitHub API token.
 
-    1. Go to your repo, "Settings" > "Actions" > "Runners" > "New Runner".
-    2. Copy the token for use later.
+    - Go to https://github.com/settings/personal-access-tokens/new
+    - Ensure `administrator:write` permission is set.
+    - Ensure the repository you want to deploy is added.
 
 3. Configure.
 
     Copy ansible inventory files in `./ansible` to `/etc/ansible`, then update the values.
 
-        cd /usr/share/ash
+        cd /usr/share/operations
+
+        # Copy default ansible files.
         cp -rf ansible/* /etc/ansible
 
-    In `/etc/ansible/hosts`, put your server's hostname.
+        # Set your hostname to in /etc/ansible/hosts and set variables in host_vars.
+        cd /etc/ansible
+        sed 's/localhost/$SERVER_HOSTNAME/g' hosts.example > hosts
+        cp host_vars/host.example.yml host_vars/$SERVER_HOSTNAME.yml
 
-    In `/etc/ansible/group_vars/ash_host.yml`, add the github users you wish to grant access, and set repo_url and the token.
+    Edit `host_vars/{$SERVER_HOSTNAME}.yml` to match your github repo's information. Insert the API key there.
 
 4. Install.
 
-        ansible-playbook /usr/share/ash/playbook.install.yml
+        ansible-playbook /usr/share/operations/playbook.yml
 
 ## Built With
 
@@ -110,20 +159,21 @@ 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
 
 Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on the process for submitting pull requests to us.
 
 ## Versioning
 
-We use [SemVer](http://semver.org/) for versioning. For the versions available, see the [releases](https://github.com/jonpugh/ash-ops/releases) page.
+We use [SemVer](http://semver.org/) for versioning. For the versions available, see the [releases](https://github.com/operations-platform/site-server/releases) page.
 
 ## Authors
 
 * **Jon Pugh** - created project from template.
 
-See also the list of [contributors](https://github.com/jonpugh/ash-ops/contributors) who participated in this project.
+See also the list of [contributors](https://github.com/operations-platform/site-server/contributors) who participated in this project.
 
 ## License
 

Taskfile.yml

@@ -0,0 +1,25 @@
+#
+# See  https://taskfile.dev/installation/
+#
+# To install to ./bin/task:
+#   sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d
+#
+version: '3'
+
+tasks:
+  start:
+    cmds:
+      - docker-compose up -d --build
+      - task: install
+
+  install:
+    cmds:
+      - docker-compose exec operations ansible-playbook /usr/share/operations/playbook.yml
+
+  destroy:
+    cmds:
+      - docker-compose kill && docker-compose rm -fv
+
+  shell:
+    cmds:
+      - docker-compose exec operations bash

ansible/ansible.cfg

@@ -1,6 +1,6 @@
 [defaults]
 stdout_callback  = yaml
-;force_color = True
+force_color = True
 ;interpreter_python = auto
 
 roles_path = ./roles

ansible/host_vars/ash.host.example.yml → ansible/host_vars/host.example.yml

@@ -2,20 +2,21 @@
 # Use a host_vars file to save server-specific variables.
 # Copy this file to one named after the server FQDN.
 
-# Add users. For each 'ash_admin_users':
+# Add users. For each 'operations_admin_users':
 # - Create a system user with sudo privileges.
 # - Add all of the users's Github SSH keys to authorized_keys.
 #
 # WARNING: Change this, unless you want to give me access to your server.
 #
-ash_admin_users:
+operations_admin_users:
   - jonpugh
 
-#
-# Replace with your repo information. Get the runner token under Settings > Actions > Runners > New Runner
-ash_github_runners:
-  - repo_url: https://github.com/jonpugh/ash-ops
-    runner_token: CopyFromAddRunnerPage
+operations_github_api_token: DefaultApiToken
+operations_github_runners:
+  - repo_name: jonpugh/operations
+    repo_host: https://github.com
     runner_name: "{{ inventory_hostname }}"
-    runner_labels: local,ash
+    # Set a runner-specific api_token, if desired.
+    api_token: "{{ operations_github_api_token }}"
+    runner_labels: local,operations
     user: platform

ansible/hosts.example

@@ -0,0 +1,7 @@
+# Place in /etc/ansible/hosts
+# This defines your local system.
+# Replace "localhost" with the FQDN of this server.
+# Install the desired hosting engine by adding it to the right group, as defined in "hosts" in playbook.yml "Configure Hosting: DDEV".
+
+[operations_host_ddev]
+localhost ansible_connection=local