Prerequisites

We intentionally wrote Spin to have little dependencies as possible. Everything is written in Bash, so it's ready to run on macOS, Windows (with WSL2), and Linux without any configuration to support running the scripts we provide.

There are a few assumptions that we have in regards to your environment:

Local Development

  • You must have a machine that has Docker installed (docker-ce or Docker Desktop)
  • For any local development domains (example myapp.dev.test), you will need to add these entries to your local host

Host File Example

The hosts file is located at /etc/hosts for macOS and Linux. For Windows, it is located at %WinDir%\System32\Drivers\Etc\Hosts.

Edit this with `sudo nano /etc/hosts` on Mac/Linux or open as Administrator in Notepad on Windows

127.0.0.1 myapp.dev.test
127.0.0.1 otherapp.dev.test
127.0.0.1 myservice.dev.test

CI/CD

You do NOT need to install the Spin script itself in CI/CD. You might find it easier to be explicit if you need to bring your services up in CI. For example:

Example of running the Spin structure in CI

on:
  workflow_call:

env:
  DOCKER_COMPOSE_CMD: docker compose -f docker-compose.yml -f docker-compose.ci.yml

jobs:
  php-unit:
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v3

      - name: Bring up containers with Docker Compose
        run: |
          $DOCKER_COMPOSE_CMD \
          up -d -V --remove-orphans

      - name: Run PHP Unit Test
        run: |
          $DOCKER_COMPOSE_CMD \
          run \
          php \
          php ./vendor/bin/phpunit --log-junit report.xml
      
      - name: Bring down containers
        run: $DOCKER_COMPOSE_CMD down -v --remove-orphans

GitHub Actions

If you're running GitHub Actions with our templates, you will need to ensure the following:

  • Your GitHub Actions plan supports environments
  • The environments are created and configured with secrets
  • You have configured every secret in your GitHub actions workflow

If you're using our default GitHub Actions templates, this includes:

  • DEPLOYMENT_SSH_PRIVATE_KEY
  • DEPLOYMENT_SSH_HOSTNAME
  • DB_ROOT_PASSWORD
  • DB_NAME
  • DB_USERNAME
  • DB_PASSWORD
  • ENV_FILE_BASE64

Production, Staging, etc

Before you run spin provision, the following must be completed:

  • You have a running Ubuntu 22.04 LTS Server running on any host of your choice
  • You have SSH access configured working between your computer and your server
  • The SSH account has sudo access to perform root-level changes
  • Your .spin-inventory is configured correctly (following Ansible's standard inventory format)
  • Your .spin.yml is configured correctly