Homelab/nomad_jobs

Nomad Job Specs

This directory contains two sub-directories: apps and services. If you are going to ignore this README you should at least read how this repository Manages Secrets.

Apps Directory

The apps directory includes the Nomad job specifications for deployable applications along with their service dependencies. In this directory, you can find the Nomad job spec for the Penpot application, which includes all the necessary services required for its deployment.

These job specs are quite large and tough to reason about so it is recommended that you use the services directory to deploy applications after having deployed their dependencies. This is a good way to just get an app up and running. You will still need to investigate the job specs to make sure they meet your requirements such as having the proper host volumes available. (By default, host volumes are not used meaning data will not persist across restarts.)

WARNING: The orchestrator could restart your service at any time. If you do not have a host volume, you will lose all your data.

Services Directory

The services directory contains standalone services that can be deployed without embedding dependencies in the job specifications. These are much smaller specs and easier to update but the administrator needs to ensure that the necessary services are deployed in advance such as Postgres being available before deploying Gitea. These dependencies are documented in the service readme.

Managing Secrets

Many of the nomad jobs require secrets to be placed in the job spec. While you could integrate with a secrets provider like Hashicorp Vault, this is an additional service to manage and maintain. I definitely encourage you to take a look as it provides a lot of value such as secret rotation and auditing.

This repo uses 1password secret references for anything such as credentials or crypto strings you would need to set upon deployment. This allows you to easily see what fields you may need to set or provides a secure way to manage all the secrets you need to deploy your applications without risking them being added to version control by mistake.

If you choose to use 1password, you will need to install the 1password cli and login to your account. You can then use the op command to retrieve secrets from their respective vault and create an output file with the secrets injected.

The 1password cli is used to retrieve secrets and inject them into the job spec. This is done through the op inject command documented here.

op inject -i postgres.nomad.hcl -o postgres.nomad.hcl.secret

Anything ending in .secret is ignored by git so you can safely output the secrets in the job spec without worrying about them being committed to version control.

Available Services

Service	Description by LLM	Service	App Spec
Caddy	Caddy is a web server and reverse proxy with automatic HTTPS written in Go.	Service Readme
Gitea	Gitea is a self-hosted Git service written in Go.	Service Readme	App Spec
Minio	MinIO is a high performance object storage server compatible with Amazon S3 APIs	Service Readme
Penpot	Penpot is the first Open Source design and prototyping platform meant for cross-domain teams. Non dependent on operating systems, Penpot is web based and works with open web standards (SVG). For all and empowered by the community.	Service Readme	App Spec
Postgres	PostgreSQL is a powerful, open source object-relational database system with over 30 years of active development that has earned it a strong reputation for reliability, feature robustness, and performance.	Service Readme
Redis	Redis is an open source (BSD licensed), in-memory data structure store, used as a database, cache, and message broker.	Service Readme