Hatchet on Ubuntu 24.04 on Azure User Guide

Overview

Hatchet is an open source distributed task queue and background job engine for durable workflow orchestration. You define workflows and tasks in code with your language SDK, and Hatchet runs them across a fleet of workers with automatic retries, concurrency and rate limits, fan out and scheduling, then shows you every run, worker, event and schedule in a modern web dashboard. The cloudimg image runs Hatchet the officially supported way, as the upstream all in one container alongside a bundled PostgreSQL and RabbitMQ, orchestrated by Docker Compose under systemd and fronted by nginx. Every image is pinned by digest and captured into the VM, so your instance starts in seconds. A unique administrator, database password, message broker password and encryption keyset are generated for each VM on first boot, before the port is reachable, and open sign up and tenant creation are disabled, so nobody can seize your instance before you sign in. Backed by 24/7 cloudimg support.

Hatchet is a trademark of its respective owner. This image is produced by cloudimg and is not affiliated with, endorsed by, or sponsored by Hatchet. It ships the free and open source MIT licensed self hosted core, unmodified.

What is included:

• Hatchet v0.94.10 (the MIT licensed self hosted core), shipped as the official all in one hatchet-lite image pinned by image digest
• A bundled PostgreSQL 16 database and a bundled RabbitMQ message broker, both pinned by image digest and reachable only inside a private Docker network (never published to a host port)
• Docker Engine (Docker CE) with the Hatchet dashboard and API published to the loopback interface only, fronted by nginx on port 80
• hatchet.service, hatchet-firstboot.service and nginx.service as systemd units, enabled and active on boot
• A unique database password, message broker password, encryption keyset and a pre seeded administrator generated per VM on first boot, never baked into the image
• A clean, empty instance on first boot: no default account, no shipped secret, no prior data
• 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet plus subnet in the target region. Standard_B2s (2 vCPU / 4 GiB RAM) is a sensible starting point; increase the size for busier engines and more workers. NSG inbound: allow 22/tcp from your management network and 80/tcp (and 443/tcp once you add TLS) for the web dashboard. If you plan to run workers outside the VM, also allow 7077/tcp for the worker gRPC endpoint. Hatchet serves plain HTTP on port 80; for production, put it behind TLS with your own domain (see the final section).

Step 1 - Deploy from the Azure Marketplace

1. In the Azure portal, choose Create a resource and search the Marketplace for the cloudimg Hatchet offer.
2. Select the plan, then Create.
3. On the Basics tab pick your subscription, resource group and region, name the VM, and select Standard_B2s (or larger).
4. Choose SSH public key authentication with admin username azureuser and provide your public key.
5. On the Networking tab, allow inbound 22/tcp from your management network and 80/tcp for the web dashboard.
6. Review and create. When the VM is running, note its public IP address.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group my-hatchet-rg \
  --name hatchet \
  --image cloudimg:hatchet:default:latest \
  --size Standard_B2s \
  --admin-username azureuser \
  --generate-ssh-keys \
  --public-ip-sku Standard

Open the port the web dashboard needs (SSH is opened by default):

az vm open-port --resource-group my-hatchet-rg --name hatchet --port 80 --priority 900

If you will connect workers from outside the VM, also open the worker gRPC port:

az vm open-port --resource-group my-hatchet-rg --name hatchet --port 7077 --priority 910

Step 3 - Connect to your VM

Replace <vm-ip> with your VM's public IP address:

ssh azureuser@<vm-ip>

Step 4 - Confirm the services are running

Hatchet, its bundled PostgreSQL and RabbitMQ, and nginx all come up automatically on first boot. Confirm they are active:

sudo systemctl is-active docker hatchet nginx

Expected output:

active
active
active

The stack runs as three containers on a private Docker network. PostgreSQL and RabbitMQ are never published to a host port; only the Hatchet dashboard and API are published, and only to the loopback interface, with nginx in front on port 80.

Step 5 - Secure by default: a unique administrator, no default account

The stock Hatchet deployment seeds a well known administrator and generates its secrets in place. The cloudimg image never ships those. On first boot, before the port is reachable, a unique administrator is created with a per VM password, the encryption and cookie secrets are regenerated per VM, and open sign up and tenant creation are disabled, so the instance cannot be seized. New members join by administrator invitation only.

You can see the whole posture at a glance. The default admin@example.com account is rejected because it was never created, a blank password is rejected, only the per VM admin password is accepted, and an attempt to register a new account is refused because open sign up is disabled:

Read your unique credentials (they are written to a root only file):

sudo cat /root/hatchet-credentials.txt

The file holds the dashboard URL, the admin email (admin@hatchet.local) and the per VM admin password. Keep it safe.

Step 6 - Sign in to Hatchet

Open http://<vm-ip>/ in your browser. You are met with the Hatchet login screen: there is no anonymous access. Sign in with the admin email and the password from the credentials file.

Step 7 - Explore the dashboard

After signing in you land on your tenant overview. The left sidebar is your home for the platform: Runs shows every task and workflow run with its status, Events is the live event feed, Logs streams task logs, and the Triggers and Resources sections cover scheduled runs, cron jobs, webhooks, workers, workflows and rate limits. The onboarding panel walks you through installing the Hatchet CLI and running your first task.

Step 8 - Workflows and tasks

A workflow defines a sequence of tasks that execute together, with retries, concurrency limits and scheduling. You register workflows from your own code using a Hatchet SDK (Python, TypeScript or Go); once a worker connects, its workflows appear here and every run is tracked end to end. Until then, the Workflows page guides you to the onboarding and the documentation.

Step 9 - Connect your workers

Workers are the processes that run your tasks. They connect to the Hatchet engine over gRPC and automatically pick up work, scaling up or down with your load. Create an API token from Settings, set it in your worker as HATCHET_CLIENT_TOKEN, point the worker at your VM's gRPC endpoint (<vm-ip>:7077), and start it. Remember to open 7077/tcp in the NSG (Step 2) if the worker runs outside the VM. Connected workers appear on the Workers page.

Step 10 - Check the stack health from the command line

Hatchet exposes an unauthenticated liveness endpoint, handy for monitoring:

curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1/api/live

Expected output (a healthy stack):

200

The public metadata endpoint confirms the security posture: open sign up and tenant creation are disabled.

curl -s http://127.0.0.1/api/v1/meta

Expected output (trimmed):

{"allowChangePassword":true,"allowCreateTenant":false,"allowInvites":true,"allowSignup":false,"auth":{"schemes":["basic"]},"authDisabled":false}

Step 11 - Invite your team

Because open sign up is disabled, add colleagues from Settings while signed in as the administrator. Invited members set their own password when they accept, and you assign them to your tenant.

Step 12 - Production: your own domain with TLS

Hatchet serves plain HTTP on port 80. For production, point a DNS record at the VM, put Hatchet behind TLS, and set the server URL to your https domain so dashboard links and worker connections use the right origin. A common approach is to add a certificate to nginx with Certbot:

sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d hatchet.example.com

Then set SERVER_URL=https://hatchet.example.com and COOKIE_DOMAIN=hatchet.example.com in /etc/hatchet/hatchet.env and restart the stack with sudo systemctl restart hatchet. With a real domain you can remove the nginx cookie domain workaround and let Hatchet set the cookie for your hostname directly. See the Hatchet documentation for the full production checklist.

Support

Every cloudimg image includes 24/7 support. If you have any questions about deploying or operating Hatchet on Azure, contact the cloudimg team through the Azure Marketplace listing or at www.cloudimg.co.uk.