Deploying to a Server

Option 1: Write your own custom deployment scripts

Stallion is a self-executing, self-hosting java jar. You can run the server on any port simply by running bin/stallion -port=8099. Thus to run Stallion on your server you just need to 1) install Java 1.8 on your server 2) write your own scripts that will upload your Stallion folder and self-executing jar to that server. 3) Use a service manager (such as systemd, upstart, monit, supervisord, etc) control the automatic starting of the Stallion service upon boot.

Option 2: Use Stablehand

Stablehand is a lightweight provisioning and deployment framework written in Python for Ubuntu servers. It handles provisioning new servers with all dependencies that Stallion needs. It also has a command for deploying Stallion instances.

Advantages of Stablehand:

• Zero downtime deploys – stallion will spin up a brand new node on a different port, make sure it is running, then switch nginx to view the new node, then tear down the previous node.
• Checks for un-run SQL migrations. If you added a new SQL migration to the sql folder, the publisher will fail if you have not yet run the SQL against production.
• Health check/smoke test support. After the publisher spins up the new node, it will check a list of URLs you can choose to make sure they are all operational.
• Asset pre-fetching. The publisher will also scan the healthcheck URLs for asset bundles, and make sure they successfully compile before putting the new node online.
• Support for multiple environments and multiple hosts per environment
• Configues systemd (Ubuntu 16) or upstart (Ubuntu 14) to manage the service, to make sure that Stallion will be started on boot and restarted if it crashes.
• Written in plain Python to make it easy to customize.

Provisioning an Ubuntu Server With Stablehand

1. Install Stablehand on your local machine:

• Ensure python3 and pip3 for python3 is installed.
• Clone the Stablehand repo – git clone git@github.com:StallionCMS/stablehand.git
• Enter the repo directory
• Run pip3 install -e . to install the Stablehand dependencies.

2. In your Stallion sites’s confdirectory, create a file called hosts.toml.

Here is a minimal example:

[[hosts]]
host="112.101.202.230"
class="StallionScheme"

Here is an example with multiple hosts and with lets-encrypt configured:

extra_features = ["lets-encrypt-autorenew"]

[feature.lets-encrypt-autorenew]
domains = ["www.stallion.io", "stallion.io", "docs.stallion.io"]
email = "maker@stallion.io"
webroot_path = "/usr/share/nginx/html"

[[hosts]]
host="qa-alfred.stallion.io"
class="StallionScheme"

[[hosts]]
host="qa-bruce.stallion.io"
class="StallionScheme"


[[hosts]]
host="prod-aragorn.stallion.io"
class="StallionScheme"

[[hosts]]
host="prod-boromir.stallion.io"
class="StallionScheme"

[[hosts]]
host="jenkins.stallion.io"
class="JenkinsMySqlScheme"

3. In your Stallion sites’s confdirectory, create a file called users.toml, or symlink to a users.toml file that you have elsewhere.

The users.toml files defines the users you want installed on each system along with their password hash (optional) and public SSH key.

Here is an example file with two users defined:

[[users]]
username = "johndoe"
public_key = "ssh-rsa asdfasfeefeAABAQDw6gjU2bUbVy7gBcOFaWKxdLwjYFgjlGZwcc1321d41QWzGx0MplXewPugPtBonBi0UsGtX+kb0/JSbNSlptI28PzP+EOtDI1FV8QJ4Us8aQEA4nDCv4pJcKh9dAB4+xiCfI6GRexBs6KULSQrqdNtug5CfQ0R2+D7wYrqBz09TnJrAgE4DoYRdZ/HG1+ng/fphTUepeZRGZqIPnrMpY/fBwAB3Bv3jkqbvaZj+v/+4uvCSEbDOto3bgzPxqmg3+OdJSkc+y0WqeTlq07dOaKfhHmDouSlkGi2gEu8gQeUTcU3JxD5ZBy1H/fgIujGwi5v2SEtjGwKeN6rLH6rCwxb name@email.net"
password_hash = "$6$rounds=10000$nB83XjX25S7.G$asdfeefHyrM9p6Exx2xs0dUpU4pAs6ESoVsadsa/pJajAyj/Kg.RvLflCiM5hBR5wg40lX82./b2gNeHjTsdfdsafQRo/yi11"


[[users]]
username = "msmith"
public_key = "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDw6gjU2bUbVy7gBcOFaWKxdLwjYFgjlGZwcc1321d41QWzGx0MplXewPugPtBonBi0UsGtX+kb0/JSbNSlptI28Pzasdfasdf+EOtDI1FV8QJ4Us8aQEA4nDCv4pJcKh9dAB4+xiCfI6GRexBs6KULSQrqdNtug5CfQ0R2+D7wYrqBz09TnJrAgE4DoYRdZ/HG1+ng/fphTUepeZRGZqIPnrMpY/fBwAB3Bv3jkqbvaZj+v/+4uvCSEbDOto3bgzPxqmg3+OdJSkc+y0WqeTlq07dOaKfhHmDouSlkGi2gEu8gQeUTcU3JxD5ZBy1H/fgIujGwi5v2SEtjGwKeasdfasdf name@email.net"
password_hash = "$6$rounds=10000$nB83XjX25S7.G$asdfeefHyrM9p6Exx2xs0dUpU4pAs6ESoVsadsa/pJajAyj/Kg.RvLflCiM5hBR5wg40lX82./b2gNeHjTsdfdsafQRo/yi11"

The SSH public key can be generated with ssh-keygen.

The password hash can be generated with this command: mkpasswd -m sha-512 –rounds=4096

The file overall uses the toml format.

4. Run the initial configuration

From your site’s directory, run python3 /path/to/stablehand/run-stablehand.py initial --user=root

The user should be the default user your server was installed with by your host. Usually this is “root”, sometimes it is “ubuntu” or something else.

This command will only ever be run once.

5. Run the main provisioning action.

Now run the initial provisioning action.

From your site’s directory, run python3 /path/to/stablehand/run-stablehand.py provision --user=myusername

The “user” should be a user that was in your users.toml file from the previous step.

Deploying to Ubuntu with Stablehand

This assumes you already have Java 1.8 and Nginx installed on an Ubuntu machine. You will also need to install Python3 with the libraries plumbum, jinja2, and requests.

1. Install Stablehand on your local machine:

1. Ensure python3 and pip3 for python3 is installed.
2. Clone the Stablehand repo git clone git@github.com:StallionCMS/stablehand.git
3. Enter the repo directory
4. run pip3 install -e . to install the Stablehand dependencies.

2. In your Stallion sites’s confdirectory, create a file called deployment.toml.

Here is a minimal example file:

[env.prod]                # this section is for the "prod" environment
hosts = ["129.202.202.100"]    # The domain or IP address of the hosts to deploy to
rootFolder = "/srv/stallion-mysite"    # Where the application files will live on the server
domain = "mysite.com" The domain at which this site will be publicly accessible

Here is a complete file with multiple environments and all possible options:

[env.qa]  # this section is for the "qa" environment
hosts = ["129.202.202.100", "129.202.202.101"]
rootFolder = "/srv/stallion-mysite"
checkUrls = ["/", "/health"]     # Path's to check for a 200 response during deploy
aliasDomains = ['qa2.mysite.com'] # domains that will also serve the main content
basePort = 13100  # The port the java server will listen on, both this port and the port one higher than this port will be used.
redirectDomains = [ 'www.qa.mysite.com'] # domains that will redirect to the primary domain
domain = "qa.mysite.com"

sslCertChain = "/etc/letsencrypt/live/mysite.com/fullchain.pem" # SSL certificate chain for serving SSL over nginx
sslPrivateKey = "/etc/letsencrypt/live/mysite/privkey.pem" # SSL private key for serving SSL over nginx
redirectToSsl = true # Redirect non-SSL requests to https://?


[env.prod]  # this section is for the "prod" environment
hosts = ["129.202.202.103", "129.202.202.105"]
rootFolder = "/srv/stallion-mysite"
checkUrls = ["/", "/health"]     # Path's to check for a 200 response during deploy
basePort = 13100
redirectDomains = ['feb2015.patfitzsimmons.com', 'patfitzsimmons.com']
domain = "www.mysite.com"
aliasDomains = ['v-2016-07.mysite.com'] # domains that will also serve the main content
sslCertChain = "/etc/letsencrypt/live/mysite.com/fullchain.pem" # SSL certificate chain for serving SSL over nginx
sslPrivateKey = "/etc/letsencrypt/live/mysite/privkey.pem" # SSL private key for serving SSL over nginx
redirectToSsl = true # Redirect non-SSL requests to https://?

3. Run the deploy command

• Go your site’s folder from the command line
• Run python3 /path/to/stablehand/run-stablehand.py deploy --env=<env> where env is either qa or prod or another environment defined in the toml file. Use deploy -h to see all available options.

Read more

For more about Stablehand, or to learn about how to customize Stablehand for your own needs, see the full Stablehand documentation.