Spin

https://github.com/serversideup/spin
Admin
Spin is a bash utility that improves the user-experience for teams using Docker by allowing them to...
Tokens:82,158
Snippets:888
Trust Score:8.3
License:GPL-3.0
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install dependencies and run dev server

Source: https://github.com/serversideup/spin/blob/main/docs/AGENTS.md

Run these commands in the docs/ directory to install dependencies and start the local development server. Then browse to http://localhost:3000 to preview changes.

```bash
cd docs/
yarn install
yarn dev
```

--------------------------------

### Initialize Spin with your project

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/1.installation/4.install-composer.md

Run spin init to start the initialization wizard for your project.

```bash
spin init
```

--------------------------------

### Start the environment with spin up

Source: https://github.com/serversideup/spin/blob/main/resources/boost/skills/spin-laravel-development/SKILL.md

Starts all services. Use --build to build images before starting (recommended for initial setup or after Dockerfile changes). -d runs in detached mode (background). Foreground mode requires a second terminal for other commands; press Ctrl+C to stop.

```bash
spin up --build    # Recommended: builds and starts all services (foreground)
```

```bash
spin up -d         # Detached mode (background)
```

--------------------------------

### Install dependencies with spin run

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/3.development-environment/1.starting-up-your-development-environment.md

Run before bringing up the environment unless you just created the project with `spin new`, which already installs dependencies. Uses `spin run` to execute PHP and Node dependency installers inside the environment.

```bash
# PHP dependencies
spin run php composer install

# Node dependencies
spin run node yarn install
```

--------------------------------

### spin run composer install example

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/9.command-reference/run.md

Runs composer install in a new container using the php service.

```bash
spin run php composer install
```

--------------------------------

### Start development server

Source: https://github.com/serversideup/spin/blob/main/docs/README.md

Start the development server on http://localhost:3000.

```bash
yarn dev
```

--------------------------------

### Example .spin.yml with v3

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/8.advanced/migrating-from-spin-v2-to-v3.md

Complete example of the new unified .spin.yml configuration file in Spin v3, which merges the previous .spin-inventory.ini and .spin.yml files. It includes commented-out examples for users, providers (DigitalOcean, Hetzner, Vultr), servers, hardware profiles, environments, and advanced server settings. Note that at least one user, one provider, and one server must be set, and provider API tokens can be set inline or via environment variables (DO_API_TOKEN, HCLOUD_TOKEN, VULTR_API_KEY). The ssh_port setting may require running `spin provision -p <your-default-ssh-port>` on first provision if changed. Passwordless sudo can be disabled by setting use_passwordless_sudo to false, which requires setting passwords for all sudo users.

```yaml
##############################################################
# 👇 Users - You must set at least one user
##############################################################

users:
  # - username: alice
  #   name: Alice Smith
  #   groups: ['sudo']
  #   authorized_keys:
  #     - public_key: "ssh-ed25519 AAAAC3NzaC1lmyfakeublickeyMVIzwQXBzxxD9b8Erd1FKVvu alice"

  # - username: bob
  #   name: Bob Smith
  #   state: present
  #   password: "$6$mysecretsalt$qJbapG68nyRab3gxvKWPUcs2g3t0oMHSHMnSKecYNpSi3CuZm.GbBqXO8BE6EI6P1JUefhA0qvD7b5LSh./PU1"
  #   groups: ['sudo']
  #   shell: "/bin/bash"
  #   authorized_keys:
  #     - public_key: "ssh-ed25519 AAAAC3NzaC1anotherfakekeyIMVIzwQXBzxxD9b8Erd1FKVvu bob"

##############################################################
# 👇 Providers - You must set at least one provider
##############################################################

providers:
#   - name: digitalocean
#     api_token: Set token here OR delete this line and set environment variable DO_API_TOKEN

#   - name: hetzner
#     api_token: Set token here OR delete this line and set environment variable HCLOUD_TOKEN

#   - name: vultr
#     api_token: Set token here OR delete this line and set environment variable VULTR_API_KEY

##############################################################
# 👇 Servers - You must set at least one server
##############################################################

servers:
  # - server_name: ubuntu-2gb-ash-1
  #   environment: production
  #   hardware_profile: hetzner_2c_2gb_ubuntu2404

  # - server_name: ubuntu-1gb-ord-2
  #   environment: staging
  #   hardware_profile: vultr_1c_1gb_ubuntu2404

##############################################################
# 🤖 Hardware Profiles
##############################################################

hardware_profiles:
  # Hetzner
  - name: hetzner_2c_2gb_ubuntu2404
    provider: hetzner
    profile_config:
      location: ash
      server_type: cpx11
      image: ubuntu-24.04
      backups: true

  # Vultr
  - name: vultr_1c_1gb_ubuntu2404
    provider: vultr
    profile_config:
      region: ord
      plan: vc2-1c-1gb
      os: "Ubuntu 24.04 LTS x64"
      backups: true
  
  # DigitalOcean
  - name: digitalocean_1c_1gb_ubuntu2404
    provider: digitalocean
    profile_config:
      region: nyc3
      size: s-1vcpu-1gb
      image: ubuntu-24-04-x64
      backups: true

##############################################################
# 🌎 Environments
##############################################################
environments:
  - name: production
  - name: staging
  - name: development

##############################################################
# 🤓 Advanced Server Configuration
##############################################################

# Timezone and contact settings
server_timezone: "Etc/UTC"
server_contact: changeme@example.com

# If you the SSH port below, you may need to run `spin provision -p <your-default-ssh-port>`
# to get a connection on your first provision. Otherwise, SSH will try connecting 
# to your new port before the SSH server configuration is updated.
ssh_port: "22"

## You can set this to false to require a password for sudo.
## If you disable passwordless sudo, you must set a password for all sudo users.
## generate an encrypted hash with `spin mkpasswd`. Learn more:
## https://serversideup.net/open-source/spin/docs/command-reference/mkpasswd
use_passwordless_sudo: true

## Email Notifications
postfix_hostname: "{{ inventory_hostname }}"

## Set variables below to enable external SMTP relay
# postfix_relayhost: "smtp.example.com"
# postfix_relayhost_port: "587"
# postfix_relayhost_username: "myusername"
# postfix_relayhost_password: "mysupersecretpassword"

## Deploy user customization - You can customize the deploy user below if you'd like
# docker_user:
#   username: deploy
#   authorized_ssh_keys: 
#     - "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKNJGtd7a4DBHsQi7HGrC5xz0eAEFHZ3Ogh3FEFI2345 fake@key"
#     - "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIFRfXxUZ8q9vHRcQZ6tLb0KwGHu8xjQHfYopZKLmnopQ anotherfake@key"

```

--------------------------------

### Example server configuration in .spin.yml

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/5.providers/0.hetzner.md

Defines a server with a name, environment, and hardware profile for Hetzner. Must set at least one server.

```yaml
##############################################################
# 👇 Servers - You must set at least one server
##############################################################

servers:
  - server_name: ubuntu-2gb-ash-1
    environment: production
    hardware_profile: hetzner_2c_2gb_ubuntu2404
```

--------------------------------

### add_user_todo_item example

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/8.advanced/99.create-your-own-template.md

Shows a message to the user after the template has been installed, prompting them to take action.

```bash
add_user_todo_item "Please update your .env file with your database credentials."
```

--------------------------------

### Install dependencies with yarn

Source: https://github.com/serversideup/spin/blob/main/docs/README.md

Install the project dependencies using yarn.

```bash
yarn install
```

--------------------------------

### Example project root with multiple compose files

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/9.command-reference/up.md

Shows a repository layout with multiple docker-compose files for different environments.

```text
.
├── docker-compose.ci.yml
├── docker-compose.production.yml
├── docker-compose.staging.yml
├── docker-compose.testing.yml
└── docker-compose.yml
```

--------------------------------

### Run hello-world container

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/1.installation/3.install-linux.md

Tests that Docker is working correctly by running the 'hello-world' container.

```bash
docker run hello-world
```

--------------------------------

### Example users configuration in .spin.yml

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/5.providers/0.vultr.md

Configure system users in your .spin.yml file. At least one user must be set.

```yaml
##############################################################
# 👇 Users - You must set at least one user
##############################################################

users:
  - username: alice
    name: Alice Smith
    groups: ['sudo']
    authorized_keys:
      - public_key: "ssh-ed25519 AAAAC3NzaC1lmyfakeublickeyMVIzwQXBzxxD9b8Erd1FKVvu alice"
```

--------------------------------

### Create the docker group

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/1.installation/3.install-linux.md

Creates the 'docker' group as part of Docker post-installation setup, allowing non-root users to run Docker commands.

```bash
sudo groupadd docker
```

--------------------------------

### Confirm Spin is working

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/1.installation/4.install-composer.md

After installation, verify spin is accessible by running this command.

```bash
bash vendor/bin/spin version
```

--------------------------------

### Confirm spin is working correctly by getting the version

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/1.installation/2.install-windows.md

Run this command in your terminal to verify that spin is installed and working. It should output the version information.

```bash
spin version
```

--------------------------------

### Example server configuration in .spin.yml

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/5.providers/0.digitalocean.md

Defines a server with a DigitalOcean hardware profile. Must set at least one server.

```yaml
##############################################################
# 👇 Servers - You must set at least one server
##############################################################

servers:
  - server_name: ubuntu-1gb-nyc-1
    environment: production
    hardware_profile: digitalocean_1c_1gb_ubuntu2404

```

--------------------------------

### Get more information on why a container won't start

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/7.server-access/2.troubleshooting-your-application.md

Use 'docker service ps' with the '--no-trunc' flag to see why a container won't start, especially when 'docker service logs' shows no logs because the service doesn't exist yet.

```bash
sudo docker service ps --no-trunc <service_name>
```

--------------------------------

### Adding New Commands - Example Action File

Source: https://github.com/serversideup/spin/blob/main/AGENTS.md

Shows the structure of a new action file in lib/actions/. The entry function is named 'action_example' and uses filtered arguments.

```bash
# lib/actions/example.sh
#!/usr/bin/env bash
action_example() {
    filter_out_spin_arguments "$@"
    local args=("${SPIN_FILTERED_ARGS[@]}")

    # Implementation here, using "${args[@]}" for the filtered arguments
    echo "Running example command"
}
```

--------------------------------

### Example server configuration in .spin.yml

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/5.providers/0.vultr.md

Defines a Vultr server with a specific hardware profile. Must set at least one server.

```yaml
##############################################################
# 👇 Servers - You must set at least one server
##############################################################

servers:
  - server_name: ubuntu-1gb-ord-2
    environment: production
    hardware_profile: vultr_1c_1gb_ubuntu2404
```

--------------------------------

### Delete Spin and reinstall

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/11.community/1.get-help.md

Remove the ~/.spin directory to go back to the stable release, then follow the installation instructions for your operating system.

```bash
rm -rf ~/.spin
```

--------------------------------

### Install latest Spin beta release

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/11.community/2.testing.md

Removes any previous installation and installs the latest beta release of Spin using the official install script with the --beta flag.

```bash
# Ensure previous installation is removed
rm -rf ~/.spin

# Install the latest release (regardless of pre-release or stable)
bash -c "$(curl -fsSL https://raw.githubusercontent.com/serversideup/spin/main/tools/install.sh)" "" --beta
```

--------------------------------

### Testing a local installation script

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/11.community/3.contributing.md

Runs the install script from a local copy of the project, useful for testing changes before submitting a pull request.

```bash
bash -c "$(cat /path/to/the-project/spin/tools/install.sh)"
```

--------------------------------

### Run spin from your project

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/1.installation/5.install-npm-yarn.md

After installation, you can access spin by running this command from your project directory.

```bash
./node_modules/.bin/spin up
```

--------------------------------

### spin configure gha production example

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/9.command-reference/configure.md

Example command to configure GitHub Actions for the production environment.

```bash
spin configure gha production
```

--------------------------------

### Create a New Project with spin new

Source: https://github.com/serversideup/spin/blob/main/README.md

Use the `spin new` command to create a new project with Spin installed. Replace `{{ your project name }}` with the desired project name.

```bash
spin new laravel {{ your project name }}
```

--------------------------------

### Install spin with NPM + Docker

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/1.installation/5.install-npm-yarn.md

Run this command from the parent folder of your project to install spin as a dev dependency using NPM via Docker. The example uses node:latest; change the image name to match your Node version.

```bash
docker run --rm -v  $(pwd):/usr/app/src -w /usr/app/src/ node npm install @serversideup/spin --dev
```

--------------------------------

### Install spin with Yarn + Docker

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/1.installation/5.install-npm-yarn.md

Run this command from the parent folder of your project to install spin as a dev dependency using Yarn via Docker. The example uses node:latest; change the image name to match your Node version.

```bash
docker run --rm -v  $(pwd):/usr/app/src -w /usr/app/src/ node yarn add @serversideup/spin --dev
```

--------------------------------

### Install a test version of Spin

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/11.community/3.contributing.md

Installs a specific branch of Spin using the install script. Change the URL to the branch you're testing if the install command itself is the feature being changed.

```bash
BRANCH="release/2.0" bash -c "$(curl -fsSL -H "Cache-Control: no-cache" https://raw.githubusercontent.com/serversideup/spin/main/tools/install.sh)"
```

--------------------------------

### Run a simple container to ensure Docker is working

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/1.installation/2.install-windows.md

Run a simple container to ensure Docker is working. It should return something like this.

```bash
docker run --rm hello-world
```

--------------------------------

### spin init usage

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/9.command-reference/init.md

Initializes Spin on an existing project using a template name. Optionally skips dependency installation with --skip-dependency-install.

```bash
spin init <template-name> [--skip-dependency-install]
```

--------------------------------

### spin run with-deps artisan test example

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/9.command-reference/run.md

Runs a test suite with dependencies started, using the --with-deps flag to include services listed under depends_on.

```bash
spin run --with-deps php php artisan test
```

--------------------------------

### Example .spin-inventory.ini

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/8.advanced/migrating-from-spin-v2-to-v3.md

Shows the v2 inventory file structure with basic server configuration and advanced environment settings. The file contains two servers, server01.example.com and server02.example.com, which need to be migrated to the .spin.yml file.

```ini
###########################################
# 👇 Basic Server Configuration - Set your server DNS or IP address
###########################################

[production_manager_servers]
server01.example.com

[staging_manager_servers]
server02.example.com

###########################################
# 🤓 Advanced Environment Settings
###########################################
# Swarm Configuration
[swarm_managers:children]
production_manager_servers
staging_manager_servers

# Environment
[production:children]
production_manager_servers

[staging:children]
staging_manager_servers

[all_servers:children]
production
staging
```

--------------------------------

### Check Docker Compose version

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/1.installation/3.install-linux.md

Checks the installed Docker Compose version. Spin requires version 2.x.

```bash
docker compose version
```

--------------------------------

### Install and use Ubuntu as your Windows Subsystem Linux distro

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/1.installation/2.install-windows.md

Run this command in PowerShell as administrator to install WSL2 with Ubuntu. A restart may be required after installation.

```bash
wsl --install -d ubuntu
```

--------------------------------

### Validate Docker is working (run this in Windows Terminal)

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/1.installation/2.install-windows.md

Run in Windows Terminal to verify Docker Desktop is installed and running. It should return version information.

```bash
docker info
```

--------------------------------

### Install spin with Composer

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/1.installation/4.install-composer.md

Run this command from the parent folder of your project to install spin as a dev dependency using Docker.

```bash
docker run --rm -it -v $(pwd):/app composer require serversideup/spin --dev
```

--------------------------------

### Install PHP extensions in Dockerfile

Source: https://github.com/serversideup/spin/blob/main/resources/boost/skills/spin-laravel-development/DOCKER-IMAGES.md

Use install-php-extensions in the Dockerfile to add PHP extensions. Always switch to USER root before installing, then back to USER www-data in subsequent stages.

```dockerfile
FROM serversideup/php:8.5-fpm-nginx-alpine AS base
USER root
RUN install-php-extensions bcmath gd intl redis
```

--------------------------------

### spin up --build example

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/9.command-reference/up.md

Forces a build of containers on initialization. Recommended when using Docker Compose configurations with build directives to ensure the latest container versions.

```bash
spin up --build
```

--------------------------------

### Example .spin.yml with migrated inventory

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/8.advanced/migrating-from-spin-v2-to-v3.md

Shows the new .spin.yml file structure after migrating the inventory from .spin-inventory.ini. The servers section must include at least one server with an address that matches the original inventory file. The hardware_profile line is optional and can be deleted if not using native providers.

```yaml
##############################################################
# 👇 Servers - You must set at least one server
##############################################################

servers:
  - server_name: server01.example.com # ✅ You can set this to anything you want. It's just a label.
    environment: production
    # 👇 You MUST set this. Make sure it matches from your ".spin-inventory.ini" file
    address: server01.example.com
    # ❌ You can delete the line below if you're not using our native providers
    # hardware_profile: hetzner_2c_2gb_ubuntu2404

  # 👇 Here is a full example of "server02.example.com" without comments
  - server_name: server02.example.com
    environment: staging
    address: server02.example.com
```

--------------------------------

### Add spin to your path

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/1.installation/2.install-windows.md

Add this to ~/.zshrc or ~/.bash_profile to manually add spin to your PATH if you did not add it during installation.

```bash
# Add this to `~/.zshrc` or `~/.bash_profile`
export PATH="$HOME/.spin/bin:$PATH"
```

--------------------------------

### Use the serversideup/spin-template-laravel-basic template

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/8.advanced/99.create-your-own-template.md

Run this command to create a new project from a community template. The user will be prompted to confirm trust in the repository before installation.

```bash
spin new serversideup/spin-template-laravel-basic
```

--------------------------------

### Install Spin (no root permissions required)

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/1.installation/2.install-windows.md

Run in WSL2 Linux shell. Installs spin at the user level in ~/.spin, using less than 300KB of storage. Spin will prompt you if you want it to modify your PATH variable.

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

--------------------------------

### Cross-Platform base64 Encoding Example

Source: https://github.com/serversideup/spin/blob/main/AGENTS.md

Shows how to handle base64 encoding differences between MacOS and Linux. Uses 'uname -s' to detect Darwin and applies the appropriate flags.

```bash
# Example: base64 encoding differs between MacOS and Linux
if [[ "$(uname -s)" == "Darwin" ]]; then
    base64 -b 0 -i "$input"
else
    base64 -w 0 "$input"
fi
```

--------------------------------

### Activate group changes

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/1.installation/3.install-linux.md

Activates the group changes immediately in the current terminal session.

```bash
newgrp docker
```

--------------------------------

### spin configure gha production --env example

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/9.command-reference/configure.md

Example command to update only the production environment file secret, skipping server connection.

```bash
spin configure gha production --env
```

--------------------------------

### Change to docs directory

Source: https://github.com/serversideup/spin/blob/main/docs/README.md

Navigate into the docs/ directory before installing dependencies or running development commands.

```bash
cd docs/
```

--------------------------------

### Docker Compose command to bring project up

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/2.getting-started/1.how-spin-works.md

Shows the verbose Docker Compose command that Spin replaces. It pulls images and starts the project with the base and development override files.

```bash
docker compose pull && docker compose -f docker-compose.yml -f docker-compose.dev.yml up
```

--------------------------------

### Start CI stack detached

Source: https://github.com/serversideup/spin/blob/main/resources/boost/skills/spin-laravel-development/TESTING.md

Step 3 of the SPIN_ENV=ci workflow. Starts the CI stack in detached mode.

```bash
SPIN_ENV=ci ./vendor/bin/spin up -d
```

--------------------------------

### spin up

Source: https://github.com/serversideup/spin/blob/main/resources/boost/skills/spin-laravel-development/COMMANDS.md

Starts all services defined in docker-compose.yml and docker-compose.$SPIN_ENV.yml. Supports all docker compose up options and always runs with --remove-orphans.

```APIDOC
## spin up

### Description
Start all services defined in `docker-compose.yml` + `docker-compose.$SPIN_ENV.yml`.

### Method
CLI

### Endpoint
`spin up [OPTIONS]`

### Parameters
#### Options
- `--skip-pull` - Optional - Do not automatically pull images
- `--force-pull` - Optional - Pull images regardless of cache

All [`docker compose up`](https://docs.docker.com/compose/reference/up/) options are supported. Always runs with `--remove-orphans`.

### Environment
- `SPIN_ENV` - Optional - Override environment (e.g., `SPIN_ENV=testing` uses `docker-compose.testing.yml`)

### Example
```bash
spin up --build
```
```

--------------------------------

### meta.yml example

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/8.advanced/99.create-your-own-template.md

Required metadata file for a Spin template. Contains title, authors, description, repository, and issues URLs. Replace with your own information.

```yaml
---
title: My Awesome Project Template
authors:
  - John Smith (@johnsmith)
  - Susan Doe (@susandoe)
description: My awesome project template is the best template ever.
repository: https://github.com/example/my-awesome-project-template
issues: https://github.com/example/my-awesome-project-template/issues

```

--------------------------------

### Enter the Ubuntu shell

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/1.installation/2.install-windows.md

After configuring WSL2, open a new PowerShell window and run this command to enter the Ubuntu shell. Always be aware of which shell you're in (Windows or Ubuntu) by checking the prompt.

```bash
wsl
```

--------------------------------

### spin help command usage

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/9.command-reference/help.md

Displays all available spin commands and provides a link to the documentation. Run this command in the terminal to get help.

```bash
spin help
```

--------------------------------

### Example removing a specific IP

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/7.server-access/2.troubleshooting-your-application.md

Example of removing the SSH host key for a specific IP address (123.45.67.89).

```bash
ssh-keygen -R 123.45.67.89
```

--------------------------------

### Comment out default providers and hardware_profiles in .spin.yml

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/5.providers/99.use-any-host.md

Shows the default commented-out providers and hardware_profiles sections that can be removed from .spin.yml. The providers block requires at least one provider, and each provider uses an api_token that can be set inline or via an environment variable (DO_API_TOKEN, HCLOUD_TOKEN, VULTR_API_KEY). The hardware_profiles define example configurations for Hetzner, Vultr, and DigitalOcean.

```yaml
# ##############################################################
# # 👇 Providers - You must set at least one provider
# ##############################################################

# providers:
#   - name: digitalocean
#     api_token: Set token here OR delete this line and set environment variable DO_API_TOKEN

#   - name: hetzner
#     api_token: Set token here OR delete this line and set environment variable HCLOUD_TOKEN

#   - name: vultr
#     api_token: Set token here OR delete this line and set environment variable VULTR_API_KEY

# ##############################################################
# # 🤖 Hardware Profiles
# ##############################################################

# hardware_profiles:
#   # Hetzner
#   - name: hetzner_2c_2gb_ubuntu2404
#     provider: hetzner
#     profile_config:
#       location: ash
#       server_type: cpx11
#       image: ubuntu-24.04
#       backups: true

#   # Vultr
#   - name: vultr_1c_1gb_ubuntu2404
#     provider: vultr
#     profile_config:
#       region: ord
#       plan: vc2-1c-1gb
#       os: "Ubuntu 24.04 LTS x64"
#       backups: true
  
#   # DigitalOcean
#   - name: digitalocean_1c_1gb_ubuntu2404
#     provider: digitalocean
#     profile_config:
#       region: nyc3
#       size: s-1vcpu-1gb
#       image: ubuntu-24-04-x64
#       backups: true
```

--------------------------------

### Reinitialize your project with spin init laravel-pro

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/8.advanced/migrating-from-spin-v2-to-v3.md

Reinitializes the project to get the latest GitHub Actions template. Warning: This deletes all Dockerfiles and Spin configurations and asks you to reinitialize your project.

```bash
spin init laravel-pro
```

--------------------------------

### Example .env file for dual-use

Source: https://github.com/serversideup/spin/blob/main/resources/boost/skills/spin-laravel-development/SKILL.md

The .env file is read by both Docker Compose (for variable substitution like ${SPIN_APP_DOMAIN}) and Laravel inside the container (since the project is volume-mounted).

```env
DB_HOST=mysql
DB_DATABASE=laravel
SPIN_APP_DOMAIN=laravel.dev.test
```

--------------------------------

### Confirm SSH access

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/5.providers/99.use-any-host.md

Use this command to verify you can connect to your server via SSH before manual setup. Replace 1.2.3.4 with your server's IP address.

```bash
# Replace 1.2.3.4 with your server's IP address
ssh root@1.2.3.4
```

--------------------------------

### Run spin configure gha <environment>

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/8.advanced/migrating-from-spin-v2-to-v3.md

Run this command for each environment to update GitHub Actions environment variables. The example shows running it for staging and production.

```bash
spin configure gha staging
spin configure gha production
```

--------------------------------

### Inspect a Docker service

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/7.server-access/2.troubleshooting-your-application.md

Use 'docker service inspect' with the '--pretty' flag to view a nicely formatted output of the service configuration, which can help identify why the service might not be starting.

```bash
sudo docker service inspect <service_name> --pretty
```

--------------------------------

### spin latest example running PHP script

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/9.command-reference/latest.md

Runs the latest stable version of PHP and executes the command `php my_script.php` inside the container. The `php` appears twice because the first is the service name and the second is the command to run inside the container.

```bash
spin latest php php my_script.php
```

--------------------------------

### Use the "source" command to apply your profile changes immediately

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/1.installation/2.install-windows.md

Run the source command to apply profile changes to your current terminal session. Use the appropriate command for your shell (ZSH or Bash).

```bash
# If you're using ZSH
source ~/.zshrc

# If you're using Bash
source ~/.bash_profile
```

--------------------------------

### Example .spin.yml file

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/4.server-configuration/3.spin-yml-usage.md

Main configuration file for Spin servers. Defines users, providers, servers, hardware profiles, environments, and advanced settings. At least one user, provider, and server must be set. Includes commented placeholders for API tokens and optional SMTP relay settings.

```yaml
##############################################################
# 👇 Users - You must set at least one user
##############################################################

users:
  - username: alice
    name: Alice Smith
    groups: ['sudo']
    authorized_keys:
      - public_key: "ssh-ed25519 AAAAC3NzaC1lmyfakeublickeyMVIzwQXBzxxD9b8Erd1FKVvu alice"

  - username: bob
    name: Bob Smith
    state: present
    password: "$6$mysecretsalt$qJbapG68nyRab3gxvKWPUcs2g3t0oMHSHMnSKecYNpSi3CuZm.GbBqXO8BE6EI6P1JUefhA0qvD7b5LSh./PU1"
    groups: ['sudo']
    shell: "/bin/bash"
    authorized_keys:
      - public_key: "ssh-ed25519 AAAAC3NzaC1anotherfakekeyIMVIzwQXBzxxD9b8Erd1FKVvu bob"

##############################################################
# 👇 Providers - You must set at least one provider
##############################################################

providers:
  - name: digitalocean
    api_token: Set token here OR delete this line and set environment variable DO_API_TOKEN

  - name: hetzner
    api_token: Set token here OR delete this line and set environment variable HCLOUD_TOKEN

  - name: vultr
    api_token: Set token here OR delete this line and set environment variable VULTR_API_KEY

##############################################################
# 👇 Servers - You must set at least one server
##############################################################

servers:
  - server_name: ubuntu-2gb-ash-1
    environment: production
    hardware_profile: hetzner_2c_2gb_ubuntu2404

  - server_name: ubuntu-1gb-ord-2
    environment: staging
    hardware_profile: vultr_1c_1gb_ubuntu2404

##############################################################
# 🤖 Hardware Profiles
##############################################################

hardware_profiles:
  # Hetzner
  - name: hetzner_2c_2gb_ubuntu2404
    provider: hetzner
    profile_config:
      location: ash
      server_type: cpx11
      image: ubuntu-24.04
      backups: true

  # Vultr
  - name: vultr_1c_1gb_ubuntu2404
    provider: vultr
    profile_config:
      region: ord
      plan: vc2-1c-1gb
      os: "Ubuntu 24.04 LTS x64"
      backups: true
  
  # DigitalOcean
  - name: digitalocean_1c_1gb_ubuntu2404
    provider: digitalocean
    profile_config:
      region: nyc3
      size: s-1vcpu-1gb
      image: ubuntu-24-04-x64
      backups: true

##############################################################
# 🌎 Environments
##############################################################
environments:
  - name: production
  - name: staging
  - name: development

##############################################################
# 🤓 Advanced Server Configuration
##############################################################

# Timezone and contact settings
server_timezone: "Etc/UTC"
server_contact: admin@example.com

# If you the SSH port below, you may need to run `spin provision -p <your-default-ssh-port>`
# to get a connection on your first provision. Otherwise, SSH will try connecting 
# to your new port before the SSH server configuration is updated.
ssh_port: "22"

## You can set this to false to require a password for sudo.
## If you disable passwordless sudo, you must set a password for all sudo users.
## generate an encrypted hash with `spin mkpasswd`. Learn more:
## https://serversideup.net/open-source/spin/docs/command-reference/mkpasswd
use_passwordless_sudo: true

## Email Notifications
postfix_hostname: "{{ inventory_hostname }}"

## Set variables below to enable external SMTP relay
# postfix_relayhost: "smtp.example.com"
# postfix_relayhost_port: "587"
# postfix_relayhost_username: "myusername"
# postfix_relayhost_password: "mysupersecretpassword"

## Deploy user customization - You can customize the deploy user below if you'd like
# docker_user:
#   username: deploy
#   authorized_ssh_keys: 
#     - "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKNJGtd7a4DBHsQi7HGrC5xz0eAEFHZ3Ogh3FEFI2345 fake@key"
#     - "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIFRfXxUZ8q9vHRcQZ6tLb0KwGHu8xjQHfYopZKLmnopQ anotherfake@key"
```

--------------------------------

### spin-mcp-wait.sh error message

Source: https://github.com/serversideup/spin/blob/main/resources/boost/skills/spin-laravel-development/SKILL.md

Error output when spin-mcp-wait.sh is used for non-MCP commands. Indicates the script is only for starting the MCP server and directs to use 'spin' directly.

```text
Error: spin-mcp-wait.sh is only for starting the MCP server. Use 'spin' directly instead.
```

--------------------------------

### Example environments configuration in .spin.yml

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/4.server-configuration/3.spin-yml-usage.md

Defines multiple environments under the `environments:` section. The `environment` property in the `servers:` section must match one of these names. The `backups` property can be set to `true` or `false` per environment; a server-level `backups` setting overrides the environment setting.

```yaml
##############################################################
# 🌎 Environments
##############################################################
environments:
  - name: production
  - name: staging
  - name: development
    backups: false
```

--------------------------------

### Add smart alias to shell profile

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/1.installation/4.install-composer.md

Add this alias to your ~/.bash_profile or ~/.zshrc to use spin from your project root. It checks node_modules first, then falls back to vendor.

```bash
alias spin='[ -f node_modules/.bin/spin ] && bash node_modules/.bin/spin || bash vendor/bin/spin'
```

--------------------------------

### Open a shell to a running container (single command)

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/7.server-access/2.troubleshooting-your-application.md

Combines the two-step process into one command using a subshell to get the container ID. Replace <service-name> with your service name; change 'sh' to 'bash' for a better experience.

```bash
# Replace <service-name> with the name of your service. This will run `sh` in the first container ID it finds.
# You can change `sh` to `bash` if your container. Bash will give you a better experience.
sudo docker exec -it $(sudo docker ps --filter "name=<service_name>" --format "{{.ID}}" | head -n 1) sh
```

--------------------------------

### Add current user to docker group

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/1.installation/3.install-linux.md

Adds the current user to the 'docker' group so they can run Docker without root privileges.

```bash
sudo usermod -aG docker $USER
```

--------------------------------

### Provision your server(s) with spin provision

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/5.providers/0.digitalocean.md

Creates and configures your server(s) with DigitalOcean for deployment.

```bash
spin provision

```

--------------------------------

### Provision your server with spin provision

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/5.providers/99.use-any-host.md

Run `spin provision -u root` to provision your server(s). Most cloud providers use `root` as the default user; replace it with your sudo username if different.

```bash
spin provision -u root
```

--------------------------------

### Example of a Docker health check failure

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/7.server-access/2.troubleshooting-your-application.md

This error message indicates the Docker health check failed, often due to a start up script sending a non-zero exit code, a configuration issue, or another problem. Ensure scripts handle exit codes properly and test them in all scenarios.

```bash
task: non-zero exit (137): dockerexec: unhealthy container
```

--------------------------------

### Open a shell to a running container (two-step process)

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/7.server-access/2.troubleshooting-your-application.md

First, get the container ID of the running service using docker ps with a name filter. Then, open a shell with docker exec -it. Replace 'sh' with any command if needed.

```bash
# Get the container ID of the running service
sudo docker ps --filter "name=<service_name>" --format "{{.ID}}"

# Run a command in the running container (you can replace "sh" with any command)
# but by default, this will open a shell to the container (type "exit" to close)
sudo docker exec -it <container_id> sh
```

--------------------------------

### Example removing a hostname and IP address

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/7.server-access/2.troubleshooting-your-application.md

Removes both hostname and IP address entries from known_hosts when a hostname was used to connect. Needed if you used a hostname to connect to the server.

```bash
ssh-keygen -R myserver.example.com
ssh-keygen -R 123.45.67.89 # Remove the IP address entry
```

--------------------------------

### Example SSH public key

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/4.server-configuration/3.spin-yml-usage.md

Shows the expected output format of an SSH public key. Copy the entire line, including the 'ssh-ed25519' part, into your .spin.yml file.

```text
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... your_email@example.com

```

--------------------------------

### Get SSH public key with cat

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/4.server-configuration/3.spin-yml-usage.md

Displays the contents of your SSH public key file. Change the filename if your key is named differently.

```bash
# Change the filename if your key is named differently
cat ~/.ssh/id_ed25519.pub

```

--------------------------------

### spin new command to create a Laravel project

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/2.getting-started/2.create-a-new-project-with-spin.md

Use the `spin new` command with the "Laravel" template to create a new project named `my-billion-dollar-idea` in the current directory. You can also specify a path to create the project in a different directory. The onboard wizard will guide you through setting up a local development environment with `spin up`.

```bash
spin new laravel my-billion-dollar-idea
```

--------------------------------

### Get debug information for spin

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/9.command-reference/debug.md

Run this command to gather environment and configuration details about spin, useful when reporting a bug to the development team.

```bash
spin debug
```

--------------------------------

### Laravel Traefik Labels Example for Soketi

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/8.advanced/3.adding-other-services.md

Shows how to replace the ports configuration with Traefik labels when using a reverse proxy like Traefik. The labels enable routing for soketi.dev.test on the websecure entrypoint with TLS, and set the load balancer to port 6001.

```yaml
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.soketi.rule=HostRegexp(`soketi.dev.test`)"
      - "traefik.http.routers.soketi.entrypoints=websecure"
      - "traefik.http.routers.soketi.tls=true"
      - "traefik.http.services.soketi.loadbalancer.server.port=6001"
      - "traefik.http.services.soketi.loadbalancer.server.scheme=http"
```

--------------------------------

### Provision your server(s) with spin provision

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/5.providers/0.vultr.md

Creates and configures your server(s) with Vultr for deployment. More options are available in the provision command reference.

```bash
spin provision
```

--------------------------------

### Delete all Docker data and start over

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/7.server-access/2.troubleshooting-your-application.md

Removes all Docker services, containers, images, networks, volumes, and configurations. Destroys all data including databases and logs. Run each command individually to verify removal.

```bash
sudo docker service rm $(sudo docker service ls -q) # Remove all services
sudo docker stop $(sudo docker ps -aq) # Stop all containers
sudo docker rm $(sudo docker ps -aq) # Remove all containers
sudo docker system prune --all # Remove all unused images and networks
sudo docker volume rm $(sudo docker volume ls -q) # Remove all volumes
sudo docker config rm $(sudo docker config ls -q) # Remove all configurations
```

--------------------------------

### spin exec example: run php artisan migrate

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/9.command-reference/exec.md

Runs 'php artisan migrate' inside the 'php' service. The service name is repeated because the first 'php' is the service and the second is the command.

```bash
spin exec php php artisan migrate
```

--------------------------------

### Usage for spin update

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/9.command-reference/update.md

Run `spin update` to update Spin to the latest version on system/user installs. This command only works when Spin is installed to the system; it will not execute if installed via Composer or Yarn.

```bash
spin update
```

--------------------------------

### Node Traefik labels example

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/8.advanced/3.adding-other-services.md

Shows how to replace port mapping with Traefik labels for routing 'mynodeapp.dev.test' to port 3000 on the Node container. All web traffic enters through Traefik first.

```yaml
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.mynodeapp.rule=Host(`mynodeapp.dev.test`)"
      - "traefik.http.routers.mynodeapp.entrypoints=websecure"
      - "traefik.http.routers.mynodeapp.tls=true"
      - "traefik.http.services.mynodeapp.loadbalancer.server.port=3000"
      - "traefik.http.services.mynodeapp.loadbalancer.server.scheme=http"
```

--------------------------------

### Set SPIN_DEBUG to true

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/11.community/1.get-help.md

Run Spin with debug logging enabled by setting the SPIN_DEBUG environment variable to true before any command. This shows exactly what Spin is running, which helps the community assist you faster.

```bash
SPIN_DEBUG=true spin version
```

--------------------------------

### Preview production build

Source: https://github.com/serversideup/spin/blob/main/docs/README.md

Locally preview the production build using yarn preview.

```bash
yarn preview
```

--------------------------------

### Exec into running container step by step

Source: https://github.com/serversideup/spin/blob/main/resources/boost/skills/spin-laravel-development/TROUBLESHOOTING.md

First find the container ID, then open a shell. Alternative to the one-liner.

```bash
sudo docker ps                                # Find the container ID
sudo docker exec -it <container_id> sh        # Open a shell
```

--------------------------------

### spin provision usage

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/9.command-reference/provision.md

Shows the command syntax for provisioning servers. The environment is optional and defaults to 'all'. Options include -h/--host, -p/--port (default 22), -u/--user (defaults to your host machine's username), and -U/--upgrade.

```bash
spin provision [environment] [ -h|--host <host> -p|--port <port> -u|--user <user> -U|--upgrade ]
```

--------------------------------

### Verify SSH access

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/5.providers/99.use-any-host.md

Test SSH connectivity before provisioning. Replace the username and IP with your own; you should connect via SSH key authentication without a password prompt.

```bash
ssh root@1.2.3.4  # Replace with your username and server IP
```

--------------------------------

### Initialize Spin with spin init

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/2.getting-started/3.add-spin-to-an-existing-project.md

Run this command in the root of your project to add Spin. Replace <template-name> with the name of the template you want to use, available from Spin Hub.

```bash
spin init <template-name>
```

--------------------------------

### Lead Paragraph Component

Source: https://github.com/serversideup/spin/blob/main/docs/AGENTS.md

Use `::lead-p` for introductory paragraphs that should stand out.

```markdown
::lead-p
This is an important introductory paragraph that summarizes the page content.
::
```

--------------------------------

### Run Ansible via Docker

Source: https://github.com/serversideup/spin/blob/main/AGENTS.md

Use this command to run Ansible playbooks without requiring a local installation, as Spin must work with only Docker installed. The command mounts the current directory into the container and uses the SPIN_ANSIBLE_IMAGE environment variable.

```bash
docker run --rm \
    -v "$(pwd):/app" \
    "$SPIN_ANSIBLE_IMAGE" ansible-playbook playbook.yml
```

--------------------------------

### add_user_todo_item

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/8.advanced/99.create-your-own-template.md

Displays a 'todo' message to the user after template installation, prompting them to take a specific action.

```APIDOC
## add_user_todo_item

### Description
Displays a 'todo' message to the user after template installation, prompting them to take a specific action.

### Usage
```bash
add_user_todo_item "Please update your .env file with your database credentials."
```

### Parameters
- **message** (string) - Required - The message to display to the user.
```

--------------------------------

### spin up usage

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/9.command-reference/up.md

Shows the basic usage syntax for the spin up command.

```bash
spin up [OPTIONS]
```

--------------------------------

### Output and User Communication Patterns

Source: https://github.com/serversideup/spin/blob/main/AGENTS.md

Shows how to use color definitions for consistent output, provide context in error messages, and choose between printf and echo.

```bash
# Color definitions (from setup_color function)
# Use these for consistent output
printf "${BOLD}${GREEN}✅ Success${RESET}\n"
printf "${BOLD}${RED}❌ Error${RESET}\n"
printf "${BOLD}${YELLOW}⚠️ Warning${RESET}\n"

# Always provide context in error messages
echo "\"$spin_action\" is not a valid command."

# Use printf for complex formatting, echo for simple messages
```

--------------------------------

### Configure Hetzner provider with API token in .spin.yml

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/5.providers/0.hetzner.md

Add the Hetzner provider to the `providers` section of your `.spin.yml` file with your API token. At least one provider must be set.

```yaml
##############################################################
# 👇 Providers - You must set at least one provider
##############################################################

providers:
  - name: hetzner
    api_token: abc123def456ghi789jkl012mno345pqr678stu901vwx234yz

```

--------------------------------

### Usage for spin new

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/9.command-reference/new.md

Shows the general syntax for the spin new command. The template-name can be an official template or a GitHub repository in the format username/repo.

```txt
spin new <template-name> <project-name>
```

--------------------------------

### Redis Environment Configuration

Source: https://github.com/serversideup/spin/blob/main/resources/boost/skills/spin-laravel-development/LARAVEL-SERVICES.md

Configure the Redis host and password. Installing Laravel Horizon automatically includes Redis.

```env
REDIS_HOST=redis
REDIS_PASSWORD=redispassword
```

--------------------------------

### spin build

Source: https://github.com/serversideup/spin/blob/main/resources/boost/skills/spin-laravel-development/COMMANDS.md

Builds images from compose files without starting containers. Wraps `docker compose build`.

```APIDOC
## spin build

### Description
Build images from compose files without starting containers.

### Method
CLI

### Endpoint
`spin build [OPTIONS]`

### Parameters
#### Options
All [`docker compose build`](https://docs.docker.com/compose/reference/build/) options are supported.
```

--------------------------------

### Build for production

Source: https://github.com/serversideup/spin/blob/main/docs/README.md

Build the application for production using yarn generate.

```bash
yarn generate
```

--------------------------------

### Spin command to bring project up

Source: https://github.com/serversideup/spin/blob/main/docs/content/docs/2.getting-started/1.how-spin-works.md

The equivalent Spin command that simplifies the Docker Compose workflow.

```bash
spin up
```
Tokens:
Raw