wanderer

Wanderer is a deployment manager for HashiCorp Nomad for automated deployments of new job versions via CI/CD pipelines.

Features

• Provides a centralized repository for Nomad HCL templates
• Offers API for CD tools to automate deployment of new versions
• Simple Web UI for editing templates & monitoring deployments
• Supports Nomad instances behind Cloudflare Access Zero Trust network
• GitHub Actions Workflow available for easy pipeline integration

See Development Project for more details.

Built with Go, Tailwind CSS and SQLite. Contains 0 lines of JavaScript 👀

Usage

As shown in the diagram above, Wanderer acts as a deployment manager between your CI/CD pipeline and your Nomad cluster. The build pipeline will instruct Wanderer to deploy a new version of a job, after which the predefined job template will be injected with the currently tagged version. Wanderer also supports multiple versions in one template, for example a web project with an API backend BACKEND_VERSION and a frontend FRONTEND_VERSION.

Nomad Job Templates

The predefined Nomad HCL templates need to contain version selectors in the following syntax: {{ VERSION_NAME }}

Example Job

The following job defined a BACKEND_VERSION which will be replaced by the actual version during deployment by Wanderer.

job "my-service" {
  type = "service"

  group "backend" {
    task "app" {
      driver = "docker"
      config {
        image = "my-service:{{ BACKEND_VERSION }}"
      }
    }
  } 
}

You can also define the version selectors in the meta block for more structure.

job "my-service" {
  type = "service"
  meta {
    version_backend = "{{ BACKEND_VERSION }}"
    version_frontend = "{{ FRONTEND_VERSION }}"
  }

  group "backend" {
    task "app" {
      driver = "docker"
      config {
        image = "my-service/backend:{{ env "NOMAD_META_version_backend" }}"
      }
    }
  }

  group "frontend" {
    task "app" {
      driver = "docker"
      config {
        image = "my-service/frontend:{{ env "NOMAD_META_version_frontend" }}"
      }
    }
  }
}

Deploy Wanderer via Docker

docker pull ghcr.io/romanzipp/wanderer:latest

See repository for more information.

Local

Build

docker build -t wanderer:latest .

Run

docker run \
  -v "$(pwd)/data/:/app/data/" \
  -v "$(pwd)/.env:/app/.env" \
  -p 8080:8080 \
  wanderer:latest

On Nomad via Docker

You can also just deploy Wanderer via Nomad itself.

job "wanderer" {
  type = "service"
  
  group "wanderer" {
    network {
      mode = "bridge"

      port "http" {
        to = 8080
      }
    }

    service {
      name = "wanderer"
      port = "http"
    }

    task "wanderer" {
      driver = "docker"

      config {
        image   = "ghcr.io/romanzipp/wanderer:latest"
        ports   = ["http"]
        volumes = [
          "local/.env:/app/.env"
        ]

        mount {
          type     = "bind"
          target   = "/app/data/"
          source   = "/opt/wanderer/data/"
          readonly = false
          bind_options {
            propagation = "rshared"
          }
        }
      }

      template {
        destination = "local/.env"
        change_mode = "restart"
        data        = <<-EOH
        APP_PASSWORD=supersecret
        SESSION_LIFETIME=43200
        EOH
      }

    }
  }
}

API

Authentication

Header: Authorization: <token>

Development

Requirements

• Go 1.19+
• Yarn
• Docker

Go app

Install dependencies

go get

Build & hot reload

gow -e=go,html run .

Frontend

Install dependencies

npm install

Build & hot reload

npm run watch

License

Released under the MIT License.

Authors

• Roman Zipp