Skip to main content

Services Synopsis

Incomplete

This document is not yet updated.

File Hierarchy​

For the lab setup, we'll be using some conventions to organize our configurations. The organization isn't based solely on making things easier for our brains, they are also organized in a way that works well with automation processes that we'll be going over in the next section.

  • In short, to setup your directory structure as this document expects, do the following:

    sudo mkdir -p /opt/{services,state,artifacts}
    sudo chown $UID /opt/{services,state}
    mkdir -p /opt/services/lab_services-config/services
    mkdir -p /opt/services/lab_services-config/contexts/caddy_svc

  • Everything I do will be in /opt. Historically, I used to do everything in /work, but I eventually found that Mac OS doesn't like users creating any old folder in the root (/) folder. Therefore, to have a convention that works universally, I now base all of my system wide work in /opt.

  • /opt/services - This is where all of our service configuration will be kept. All of this configuration should eventually be revision controlled. But to bootstrap ourselves, we'll have to do without until our Gitea (git) service is available.

    • /opt/services/lab_services-config - This'll eventually be revision controlled in its own git repo. When git repos contain unsafe content like credentials, tokens, and passwords that should not be made public, I use the convention to include the suffix -config.

      The file contents of this folder will include scripts to simplify development, testing, and automation. It also includes aggreagate docker compose yaml that uses the include attribute.

    • /opt/services/lab_services-config/contexts - This is a set of folders to be used as container image build contexts. For example, we embed the caddy_svc Caddyfile into the container image, so we put the Caddyfile into the /opt/services/lab_services-config/contexts/caddy_svc folder.

    • /opt/services/lab_services-config/services - This is a folder where we store all of the specific docker compose service descriptors. One service per file makes the files more readable and usable in aggreagate docker compose yaml that uses the include attribute.

  • /opt/state - This is where all of the state generated by our services will be generated and stored. This can be persistent databases, temporal save states, or default configuration. In the case where there configuration in the state folder that we want to control or manage, it should be captured into revision control and either updated on every rollout or more ideally embedded into the container image.

    Note: We keep /opt/state separate from /opt/services because /opt/state is the data that needs to be backed up (and possibly snapshotted). The container images shouldn't need to be backed up because they already exist in the Gitea repositories and if we do backup the binaries, it'd be part of the /opt/artifact backup or gitea_svc state backup.

  • /opt/artifacts - In general, this is for built binaries, images, and other types of output artifacts. Since these should all be things that can be repeatably generated, there backup policy is vastly lower than other backup policies.

All The Things Without The Words​

Planning to make available in git or zip soon.