Spokes v1.4.1

Published at April 3, 2023 ·  5 min read

We’re pleased to announce Spokes v1.4.1! This release introduces new features, improvements, and fixes to user-reported issues.

Installing the Update

Spokes can be updated using dnf or yum if the repositories have been set up.

A manual update can be performed as well by downloading v1.4.1 from our site to the host running Spokes and running this command:

[user@host ] sudo rpm -Uvh spokes-1.4.1-1.x86_64.rpm

If you’ve created your Spokes server with v1.3.2 or earlier, please review the section below and manually run a database migration script included in this release. This script must be run for Spokes to run correctly after applying this update if your host meets the v1.3.2 or earlier criteria.

Database Migration

Important Note for users with an instance of Spokes that was first deployed using v1.3.2 or earlier. You will need to perform the following commands after installing Spokes v1.4.1.

# 1.) after installing the latest package via yum/dnf or manually, stop the spokes service.
[user@host ] sudo systemctl stop spokes

# 2.) run the clean-clone DB migration script and copy the output database to the spokes data directory in /var/lib/spokes.
[user@host ] sudo -u spokes bash
[spokes@host ] /usr/share/spokes/db-clone-clean.sh
[spokes@host ] cp /tmp/spokes-db-migration/spokes.db /var/lib/spokes/
[spokes@host ] exit

# 3.) restart the spokes service.
[user@host ] sudo systemctl start spokes

# 4.) review the service output to ensure it was restarted correctly.
[user@host ] journalctl -u spokes -f -n 100

This migration script is necessary since we’ve updated it to the latest version of the underlying database package that Spokes use.

For some history, Spokes initially implemented all of its database functions using the default SQL package in Go. We transitioned to using GORM in v1.3.2, and the created database was compatible with GORM’s schema management.

With the latest version of GORM, those older databases were no longer compatible. To resolve this, we created the db-clean-clone.sh script that creates a temporary empty database and imports all the data from /var/lib/spokes/spokes.db to it. Now we have a database whose schema has been created from the beginning by GORM and all of our original data.

Have any questions or concerns? Would you like us to help supervise applying this upgrade? Just reach out to us.

Container Improvements

We’ve made improvements in this release to how we containerize Spokes and make it simple to deploy our image.

Our original target was RPM-based Linux systems, so we utilized two primary directories: /etc/ and /var/lib, for configuration and runtime data. Our original container images were built to mirror those conventions and forced users to create two volumes mounted into the container for /etc/spokes and /var/lib/spokes. This isn’t convenient and makes users have to back-up two directories.

To improve this, we’ve added /var/lib/spokes/config as a default directory to search for a configuration file. Only one volume must be mounted to the container to /var/lib/spokes.

Below is an example of the directory tree of a container with the configuration directory config as a sub-directory. You can see the certificates directory certs that is used when LetsEncrypt is enabled. The directory for custom or self-signed certificates will be created here as well.

[root@58ba330 ] tree /var/lib/spokes

|-- certs-extra
|-- config
|   |-- certs
|   |   |-- acme
|   |   |-- certificates
|   |   |-- locks
|   |   |-- ocsp
|   |-- config.json
|-- licenses
|   |-- license.json
|-- releases
|-- sessions
|   |-- 003901b43a9d0e5c5b3c892d705f8ebe94d99667
|   |-- 003acc80259ebf1f7c2f82ce019dc0cd7e7ded16
|   |-- 00577a5451a140ed69055bbc01956ef756aa21af
|-- spokes-events.db
|-- spokes-metrics.db
|-- spokes.db

Enable LetsEncrypt

We’ve added a new environment variable LETS_ENCRYPT that can be used to enable LetsEncrypt when the container instance auto-configures itself for the first time. To enable you must set the value to true. Below is an example of the environment object in a docker-compose file and other typically defined variables such as ADMIN_SECRET, REGISTRATION_TOKENS, and ADMIN_API_TOKENS.

    environment:
      - DOMAIN=spokes.example.com
      - ADMIN_SECRET=7ee82a6451146814
      - LETS_ENCRYPT=true
      - REGISTRATION_TOKENS=0647e2d67b0a5499937c3606858ba330
      - ADMIN_API_TOKENS=65b372f3fc0cbe53706d0c4d635bb293

External ACME Accounts

LetsEncrypt is the most popular ACME provider, but several others exist, such as ZeroSSL. These providers are configured using a custom ACME endpoint, a key ID, and a MAC key.

Spokes v1.4.1 adds new environment variables that it will use to auto-configure the use of an external ACME account when it’s deployed as a container. These variables include ACME_ENDPOINT, ACME_KEY_ID, and ACME_MAC_KEY.

Below is an example showing how they can be added to a docker-compose file and used during initial auto-configuration of the container.

    environment:
      - DOMAIN=spokes.example.com
      - ACME_ENDPOINT=https://acme.zerossl.com/v2/DV90
      - ACME_KEY_ID=<KEY ID>
      - ACME_MAC_KEY=<MAC KEY>

You cannot combine using LetsEncrypt with an external ACME account, at least not yet. The Spokes auto-configuration routine will prioritize LetsEncrypt over the external account.

Configuration File Updates

In the container improvements section, we described enabling external ACME accounts, such as those with ZeroSSL. Containers are best configured by using the environment variables. However, if you’ve deployed Spokes using our RPM package or have an existing container deployed, then updating your configuration file manually is necessary to use an external ACME account.

Below is an example of the tls block in the configuration that will set up an external ACME account.

{
	"tls": {
		"ca": "https://acme.zerossl.com/v2/DV90",
		"keyID": "KEY_ID",
		"mac": "MAC_KEY"
	}
}

Thanks!

We appreciate all the inputs and suggestions you’ve sent us! Let us know if we can focus on any new features or improvements we can add to Spokes.

Cheers!