Getting Started¶
Getting started with docker¶
You need nomad and docker installed on your system
- Clone the repo
- Start 2 terminal sessions at the root of this repo
Run the following in the first terminal:
Make sure that docker volumes are available
You can use the provided.deployment/nomad/agent.hclas a reference
nomad agent -dev -bind 0.0.0.0 -log-level INFO -config .deployment/nomad/agent.hcl
This will bring up a nomad environment with docker volumes enabled. See nomad docs for more info.
Run the following in the second terminal:
nomad namespace apply nomad-ops
This makes sure that the namespace nomad-ops exists.
Deploy Nomad-Ops to nomad by running:
nomad job run .deployment/nomad/docker.hcl
Go to http://localhost:8080/_/.
This will bring you to the login screen of pocketbase.
Login using admin@nomad-ops.org and simple-nomad-ops.
Once you are logged in, you are able to create your first normal user. Just hit + New Record for the User collection and fill out the form. Afterwards you can access the UI of Nomad-Ops at http://localhost:8080/ and use your newly created credentials to login.
The Admin User
admin@nomad-ops.orgis only capable to access the pocketbase ui athttp://{your-nomad-ops-host}/_/. To access the Nomad-Ops UI you need to create a normal user first.
Installation Notes¶
Nomad Ops can be installed inside or outside of your nomad-cluster.
If you install Nomad Ops inside your cluster you can leverage the Workload Identities of Nomad v1.5.x.
Keep in mind that Nomad Ops stores its data on the local file system. Please use a NFS-mount or similar to enable scheduling around the cluster.
For a simple deployment, consider restricting the deployment to a specific node.
Configuration¶
| ENVIRONMENT Variable | Default | Description |
|---|---|---|
| DEFAULT_ADMIN_EMAIL | admin@nomad-ops.org | On first startup an admin user is created with this email |
| DEFAULT_ADMIN_PASSWORD | simple-nomad-ops | On first startup an admin user is created with this password |
| NOMAD_ADDR | '' | Nomad addr |
| NOMAD_TOKEN | '' | Nomad token to access the Nomad API |
| NOMAD_TOKEN_FILE | '' | If set will ignore NOMAD_TOKEN and read from this file instead |
| TRACE | FALSE | If set to TRUE enables detailed logging |
| SLACK_WEBHOOK_URL | '' | Set to your Webhook URL if you want to receive notifications about deployments |
| SLACK_BASE_URL | 'localhost:3000/ui/' | included in the slack message as a link |
| SLACK_ICON_SUCCESS | ':check:' | Icon to use for successful deployments |
| SLACK_ICON_ERROR | ':check-no:' | Icon to use for unsuccessful deployments |
| SLACK_ENV_INFO_TEXT | 'Sent by nomad-ops (dev)' | Send as a footer in the slack message |
There are a couple of Pocketbase settings that you can set as well. See here.
Email Settings¶
Pocketbase integrates a couple of workflows for user management (confirmation, password reset, ...). To use that please adjust the environment variables according to the docs. See here for the corresponding environment variables in Nomad-Ops.
Security¶
Deploy keys are saved in plain text. Please make sure that the application is only accessible by authorized personnel. This includes setting up TLS, users and a hardened runtime-environment.
Workflow¶
Nomad Ops pulls the desired state from a git-repository on a regular basis. Additionally, certain events trigger a re-evaluation of the state as well.
After the desired state has been fetched, the current state is queried from the nomad-cluster. The reconciler performs the necessary steps to bring the cluster state closer to the desired state by adding, updating or deleting jobs.
User management¶
Users are currently managed by the admin interface of pocketbase
Restrictions¶
Nomad Ops does not perform any templating or rendering and expects the manifests in the repository to be ready-to-run. Adjust your CI/CD pipeline to include the rendering step before you commit the file in the repository.
Do not store secrets in plain text in your repository. Consult the nomad docs on best practices to provide secrets to your jobs.