Preparing your server

Spin gives you the power to choose any host that you want. Although the responsibility is on your shoulders to get a server set up, Spin makes it very easy to get this accomplished.

Choose a host

Choose any host that:

  • Gives you root access to a system running Ubuntu 22.04
  • Allows root SSH access
  • Has backup/snapshot services (highly recommended)
  • It's usually best for you run this on a brand new server with a fresh installation

Configure your DNS

Ensure that you have DNS configured to point your server hostname (optional, but highly recommended).

Configure server inventory and settings

There are two files that will need to be configured:

  • .spin-inventory.ini
  • .spin.yml

Inventory

We call the list of our servers "inventory". This follows the Ansible Inventory format. For example, if you wanted to add server01.example.com as the production server, we would configure our file to look like this and add this server to go underneath the production_manager_servers group:

.spin-inventory.ini: Add `server01.example.com` to Production

####################
# Host Types
####################

[production_manager_servers]
server01.example.com

[staging_manager_servers]
# server02.example.com

####################
# Swarm Roles
####################
[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

Configure other server settings

In the .spin.yml file, you will find many other settings. There are a few things that you will want to check here:

👉 Required to be changed

KeyDescription
server_contactChange this to a valid email. If you're using our Traefik templates, you'll also need to change the letsencryptresolver.acme.email key under the .infrastructure/conf/traefik/prod/traefik.yml file.
docker_user.authorized_ssh_keysThis must be the public key of the your dedicated SSH keypair that you generated.
users.usernameSet this to a username that you'll remember. Be sure to not use any weird characters.
users.passwordSet this to the hash generated with mkpasswd.
users.username.authorized_ssh_keysSet this to your public SSH key value. ⚠️ The key pair must be accessible under ~/.ssh on your host.

.spin.yml

---
###########################################
# Basic Server Configuration
###########################################
server_timezone: "Etc/UTC"
server_contact: changeme@example.com # 👈 Change this

# SSH
ssh_port: "22"

## Email Notifications
postfix_hostname: "{{ inventory_hostname }}" # ✅ Set automatically

## 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
##############################################################
docker_user:
  username: deploy
  uid: 9999
  group: deploy
  secondary_groups: "docker"
  gid: 9999
  ## Uncomment to set authorized SSH keys for the docker user.
  authorized_ssh_keys: 
    - "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKNJGtd7a4DBHsQi7HGrC5xz0eAEFHZ3Ogh3FEFI2345 fake@key" # 👈 Change this
  #   - "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIFRfXxUZ8q9vHRcQZ6tLb0KwGHu8xjQHfYopZKLmnopQ anotherfake@key"

##############################################################
# Users
##############################################################

### Use the template below to set users and their authorized keys
## Passwords must be set with an encrypted hash. To do this, see the Ansible FAQ.
## Your best bet is probably using the `mkpasswd` on a Linux machine.
## https://docs.ansible.com/ansible/latest/reference_appendices/faq.html#how-do-i-generate-encrypted-passwords-for-the-user-module

users:
  - username: alice # 👈 Change this
    name: Alice Smith  # 👈 Change this
    state: present
    groups: ['adm','sudo']
    password: "$6$mysecretsalt$qJbapG68nyRab3gxvKWPUcs2g3t0oMHSHMnSKecYNpSi3CuZm.GbBqXO8BE6EI6P1JUefhA0qvD7b5LSh./PU1" # 👈 Change this
    shell: "/bin/bash"
    authorized_keys:
      - public_key: "ssh-ed25519 AAAAC3NzaC1lmyfakeublickeyMVIzwQXBzxxD9b8Erd1FKVvu alice" # 👈 Change this

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

Run spin provison

Once you have .spin.yml and .spin-inventory.ini configure, you're ready to provision your server(s).

Provision your server(s)

spin provision

This process will automatically download our Ansible collection and apply the changes on your server.

Confirm everything works

To confirm everything works as expected, try to SSH into your server using the username you created before. You will be prompted to change your password to a new password as soon as you login.

Provision your server(s)

ssh -p 22 myuser@server01.example.com

If you get a connection, you should be ready to receive deployments to Docker Swarm via SSH 🥳

Next Steps

Prepare GitHub Actions for Deployment →