.spin.yml Usage

The .spin.yml file is the main configuration file for using servers with Spin. It is used to configure your users, providers, servers, hardware profiles, environments, and more.

Example `.spin.yml` file

Here's an example of what the .spin.yml file looks like:

.spin.yml

##############################################################
# 👇 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"

Users

You'll need to configure a user for your server. This will be the user that you use to SSH into your server.

For your best user experience, you might want to consider having the username match the username on your host machine. You can run whoami to see your current username and use that as the username in your .spin.yml file.

.spin.yml Server Users

##############################################################
# 👇 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"

The above configuration is creating two users: alice and bob. Both users are added to the sudo group, which allows them to use sudo to run commands with elevated privileges (such as sudo su to get a root shell).

Variable	Description	Example
`username`	The username of the user.	`alice`
`name`	The full name of the user.	`Alice Smith`
`groups`	The groups the user belongs to. Separate multiple groups with a comma.	`['sudo', 'docker']`
`authorized_keys.public_key`	The authorized public SSH key that can connect to the server for this user.	`ssh-ed25519 AAA...d1FKVvu alice`
`password`	The encrypted password for the user. Generate an encrypted hash with `spin mkpasswd`. The user will be prompted to change their password on first login. The password will only be used if `use_passwordless_sudo` is set to `false`.	`$6$mysecretsalt$...`

Setting your SSH public key

To get your SSH public key, look for files under your ~/.ssh folder. The filename could be something like id_ed25519.pub or id_rsa.pub. Just make sure the file ends with .pub.

Once you find the file, you can get the contents of the public key by running this command:

Get SSH public key

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

You should see something that looks like this:

Example SSH public key

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

Copy the entire line (including the "ssh-ed25519" part) and paste it into your .spin.yml file as shown in the example above.

Generating a new SSH key

If you need to generate a new SSH key, see our guide on generating a secure SSH key.

Providers

Providers are only required if you want Spin to automatically create servers. If you're using existing servers, see our guide on using your own servers with Spin.

The providers: section in your .spin.yml configures connections to supported cloud providers. Spin natively supports these providers:

Provider	Configuration Name	Environment Variable
DigitalOcean	`digitalocean`	`DO_API_TOKEN`
Hetzner	`hetzner`	`HCLOUD_TOKEN`
Vultr	`vultr`	`VULTR_API_KEY`

API tokens grant powerful access to your cloud resources. For better security, you may consider storing your API tokens as environment variables on your local machine (using .env files or your preferred secure method) instead of directly in .spin.yml.

Click on any provider name above for detailed configuration instructions.

Hardware Profiles

The hardware_profiles: section defines the server resources and provider for each server. Each hardware profile references a provider and specifies the server's resources.

Each hardware profile structure is slightly different depending on the provider. Click on a provider name above for detailed configuration instructions.

Servers

The servers: section defines the servers that Spin will create and manage. Each server requires a few key properties to determine its configuration.

Here's an example of configuring two servers:

.spin.yml

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

Property	Description	Example	Required
`server_name`	A unique, descriptive name for your server. Use alphanumeric characters and hyphens only (no spaces or special characters).	`web-server-1`	Yes
`environment`	The deployment environment (`production`, `staging`, `development`). Must match an environment defined in your `.spin.yml` file.	`production`	Yes
`hardware_profile`	References a hardware profile defined in your `.spin.yml` that specifies the server's resources and provider.	`hetzner_2c_2gb_ubuntu2404`	Only if you intend to use a provider
`address`	The server's IP address or hostname. Leave blank for auto-assigned IPs - Spin will update this after provisioning. Using existing servers? ⚠️ You must specify the IP address or hostname here.	`1.2.3.4`	Only if you are using existing servers

Environments

Environments are managed under the environments: section in your .spin.yml file. You can define as many environments as you'd like or change the names of the environments.

The most important thing to remember is the environment property in the servers: section must match an environment defined in your .spin.yml file.

You can also set the backups property to true or false to enable or disable backups for the environment. If the backups property is set on a server, it will override the environment setting.

Example environments configuration in .spin.yml

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

Advanced Server Configuration

We also give you a few other options to configure your servers that will configure the behavior for the Spin Ansible Collection.

.spin.yml Advanced Server Configuration

##############################################################
# 🤓 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"

Encrypting your `.spin.yml` file

It is possible that if you want to encrypt your .spin.yml file for security reasons, you can use the spin vault command which will use Ansible Vault to securely encrypt your file.

If you do choose to encrypt your .spin.yml file, just be sure to add the .vault-password file so Ansible can securely decrypt it when it runs.

Learn more about "spin vault" →

Introduction

Installation

Getting Started

Development Environment

Server Configuration

Providers

Deployment

Server Access

Advanced

Command Reference

Community

.spin.yml Usage

Example `.spin.yml` file

.spin.yml

Users

.spin.yml Server Users

Setting your SSH public key

Get SSH public key

Example SSH public key

Generating a new SSH key

Providers

Hardware Profiles

Servers

.spin.yml

Environments

Example environments configuration in .spin.yml

Advanced Server Configuration

.spin.yml Advanced Server Configuration

Encrypting your `.spin.yml` file