# Spin

Spin is a bash utility that improves the developer experience when working with Docker, enabling teams to replicate any environment on any machine (macOS, Windows, or Linux). It serves as a wrapper around Docker Compose and Docker Swarm, providing simplified commands for local development, server provisioning, and zero-downtime deployments. Spin centralizes infrastructure configuration, making it easy to maintain consistent development and production environments.

The tool integrates with Docker (Desktop, Compose, and Swarm Mode), Ansible for server provisioning, and GitHub Actions for CI/CD automation. Spin uses official templates to scaffold new projects with pre-configured Docker setups, supporting frameworks like Laravel and Nuxt. It handles complex operations like SSL automation, server management, and deployment orchestration through simple command-line interfaces.

## Installation

Install Spin globally on your system using the simple install script.

```bash
# Quick install via curl
bash -c "$(curl -fsSL https://raw.githubusercontent.com/serversideup/spin/main/tools/install.sh)"

# Or install via NPM
npm install -g @serversideup/spin

# Or install via Composer (PHP projects)
composer require serversideup/spin
```

## spin new - Create New Project

Creates a new project from a template with all necessary Docker configuration files pre-configured for local development and production deployment.

```bash
# Create a new Laravel project with Spin
spin new laravel my-awesome-app

# Create a project from a custom GitHub template
spin new username/custom-template my-project

# Create from a specific branch
spin new laravel my-app --branch develop

# Skip dependency installation
spin new laravel my-app --skip-dependency-install
```

## spin init - Initialize Existing Project

Adds Spin configuration to an existing project, copying template files and setting up Docker Compose configurations.

```bash
# Initialize an existing Laravel project with Spin
spin init laravel

# Initialize from a GitHub repository template
spin init serversideup/spin-template-nuxt

# Initialize from local template source
spin init laravel --local /path/to/template
```

## spin up - Start Development Environment

Starts all Docker containers defined in docker-compose.yml and environment-specific compose files. Automatically pulls updated images based on configured intervals.

```bash
# Start all services in development mode
spin up

# Start services in detached mode (background)
spin up -d

# Start with forced image pull
spin up --force-pull

# Start without pulling images
spin up --skip-pull

# Start specific service only
spin up php

# Use different environment (loads docker-compose.staging.yml)
SPIN_ENV=staging spin up -d
```

## spin down - Stop Development Environment

Stops and removes all containers, networks, and orphaned containers from the Docker Compose project.

```bash
# Stop all services and remove containers
spin down

# Stop and remove volumes
spin down -v

# Stop and remove images
spin down --rmi all
```

## spin exec - Execute Commands in Container

Executes a command inside a running container, useful for running artisan commands, database migrations, or debugging.

```bash
# Run Laravel artisan command
spin exec php php artisan migrate

# Open bash shell in PHP container
spin exec php bash

# Run npm commands in node container
spin exec node npm install

# Run composer commands
spin exec php composer require laravel/sanctum
```

## spin run - Run One-off Commands

Runs a one-off command in a new container without starting linked services. Useful for running scripts or commands that don't need the full stack.

```bash
# Run migrations without starting other services
spin run php php artisan migrate

# Run tests
spin run php php artisan test

# Install composer dependencies
spin run php composer install

# Run with forced pull
spin run --force-pull php php artisan optimize
```

## spin build - Build Docker Images

Builds Docker images defined in docker-compose.yml with build configurations.

```bash
# Build all services
spin build

# Build specific service
spin build php

# Build without cache
spin build --no-cache

# Build with build arguments
spin build --build-arg APP_ENV=production
```

## spin logs - View Container Logs

Displays logs from running containers for debugging and monitoring.

```bash
# View logs from all services
spin logs

# Follow logs in real-time
spin logs -f

# View logs from specific service
spin logs php

# View last 100 lines
spin logs --tail 100 php

# View logs with timestamps
spin logs -t php
```

## spin provision - Provision Production Servers

Provisions production servers using Ansible playbooks, installing Docker, configuring security settings, and preparing for deployments.

```bash
# Provision all servers in production group
spin provision production

# Provision specific host
spin provision --host myserver.com production

# Provision with custom SSH user
spin provision --user deploy production

# Provision with custom SSH port
spin provision --port 2222 production

# Force reinstall Ansible Galaxy dependencies
spin provision --upgrade production
```

## spin deploy - Deploy to Production

Builds Docker images, creates SSH tunnels, and deploys to Docker Swarm clusters with zero-downtime using rolling updates.

```bash
# Deploy to production environment
spin deploy production

# Deploy to staging environment
spin deploy staging

# Deploy with custom SSH user
spin deploy --user deploy production

# Deploy with custom compose files
spin deploy -c docker-compose.yml -c docker-compose.prod.yml production

# Deploy with custom SSH port
spin deploy --port 2222 production
```

## spin maintain - Run Maintenance Tasks

Executes Ansible maintenance playbooks on production servers for updates, backups, or other administrative tasks.

```bash
# Run maintenance on production servers
spin maintain production

# Run maintenance on specific host
spin maintain --host myserver.com production

# Run with custom SSH user
spin maintain --user admin production
```

## spin configure gha - Configure GitHub Actions

Sets up GitHub Actions secrets and environment variables for automated CI/CD deployments.

```bash
# Configure GitHub Actions for production deployment
spin configure gha production

# Configure for staging environment
spin configure gha staging
```

## spin vault - Manage Encrypted Secrets

Encrypts and decrypts sensitive configuration files using Ansible Vault for secure storage in version control.

```bash
# Encrypt a file
spin vault encrypt .spin.yml

# Decrypt a file
spin vault decrypt .spin.yml

# Edit encrypted file in place
spin vault edit .spin.yml

# View encrypted file contents
spin vault view .spin.yml

# Re-encrypt with new password
spin vault rekey .spin.yml
```

## spin gh - GitHub CLI Integration

Provides GitHub CLI functionality through Docker when gh is not installed locally. Supports all standard gh commands.

```bash
# Authenticate with GitHub
spin gh auth login

# Create a new repository
spin gh repo create my-new-repo --public

# Create a pull request
spin gh pr create --title "Feature: Add new endpoint" --body "Description here"

# List issues
spin gh issue list

# View repository information
spin gh repo view
```

## Environment Configuration

Configure Spin behavior through environment variables. Set `SPIN_ENV` to load environment-specific compose files.

```bash
# Use multiple environments (loads docker-compose.dev.yml and docker-compose.debug.yml)
SPIN_ENV=dev,debug spin up

# Enable debug mode for verbose output
SPIN_DEBUG=true spin up

# Custom Docker Compose command
COMPOSE_CMD="docker-compose" spin up

# Custom PHP image for run commands
SPIN_PHP_IMAGE="serversideup/php:8.3-fpm" spin run php php -v

# Custom Node image
SPIN_NODE_IMAGE="node:22" spin run node node -v

# Custom Ansible image for provisioning
SPIN_ANSIBLE_IMAGE="serversideup/ansible-core:2.18-alpine" spin provision production
```

## Docker Compose File Structure

Spin automatically merges docker-compose.yml with environment-specific files based on SPIN_ENV.

```yaml
# docker-compose.yml - Base configuration
services:
  php:
    image: serversideup/php:8.3-fpm-nginx
    volumes:
      - .:/var/www/html
    ports:
      - "80:80"
      - "443:443"

  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: ${DB_PASSWORD}
      MYSQL_DATABASE: ${DB_DATABASE}
    volumes:
      - mysql_data:/var/lib/mysql

volumes:
  mysql_data:
```

```yaml
# docker-compose.dev.yml - Development overrides
services:
  php:
    build:
      context: .
      dockerfile: Dockerfile
    environment:
      APP_DEBUG: "true"
    volumes:
      - .:/var/www/html:cached
```

## Spin Configuration File (.spin.yml)

The `.spin.yml` file configures server provisioning and deployment settings.

```yaml
# .spin.yml - Server and deployment configuration
servers:
  production:
    hosts:
      - hostname: prod.example.com
        ip: 192.168.1.100
    users:
      - username: deploy
        groups: docker,sudo
        authorized_keys:
          - "{{ lookup('file', '~/.ssh/id_ed25519.pub') }}"

  staging:
    hosts:
      - hostname: staging.example.com
        ip: 192.168.1.101
    users:
      - username: deploy
        authorized_keys:
          - "{{ lookup('file', '~/.ssh/id_ed25519.pub') }}"

docker_swarm:
  enabled: true
  manager_host: prod.example.com

use_passwordless_sudo: true
```

## Summary

Spin excels at bridging the gap between local development and production deployment by providing a unified Docker-based workflow. Its primary use cases include rapid project scaffolding with `spin new`, seamless local development with `spin up/down/exec`, and streamlined production deployments using `spin provision` and `spin deploy`. The integration with Ansible ensures servers are configured consistently, while Docker Swarm support enables zero-downtime deployments with rolling updates.

For teams looking to standardize their development environments and deployment pipelines, Spin provides an opinionated but flexible framework. The tool integrates naturally with existing Docker and Docker Compose workflows while adding powerful features like encrypted secrets management via Ansible Vault, GitHub Actions configuration, and automated server provisioning. Whether you're a solo developer wanting consistent environments or a team needing reproducible deployments, Spin reduces the complexity of Docker orchestration to simple, memorable commands.