azimuthal

module
v0.1.21 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 3, 2026 License: Apache-2.0

README

Azimuthal

A fully open-source, self-hostable alternative to the Atlassian suite (Jira, Confluence, Jira Service Desk), built in Go.

License: Apache 2.0 — Azimuthal is fully open source. All features are available to all users.

Features

  • Service Desk — ticket lifecycle, email ingestion, kanban boards
  • Wiki — page tree, markdown rendering, version history, conflict detection
  • Project Tracking — backlog, sprints, roadmap, cross-tool linking
  • Unified Frontend — React + TypeScript SPA embedded in the Go binary, dark mode by default
  • SSO — SAML/OIDC single sign-on
  • RBAC — role-based access control
  • Audit Log — append-only event logging

What works today

  • Single binary — make build produces one binary with the frontend embedded. Run ./azimuthal serve and visit http://localhost:8080
  • Docker Compose self-hosting — docker compose -f build/docker-compose.yml up -d runs the full stack (app + PostgreSQL + MinIO)
  • Backup and restore — azimuthal backup --output backup.tar.gz creates a full archive; azimuthal restore --input backup.tar.gz restores it
  • Admin CLI — azimuthal admin create-user and azimuthal admin reset-password for user management
  • Dark mode by default — steel blue and silver design system with light mode opt-in via settings
  • Service Desk — ticket list, ticket detail, kanban board with drag-and-drop
  • Wiki — page tree with collapsible navigation, markdown rendering
  • Project Tracking — backlog view, sprint board with drag-and-drop
  • Unified navigation — top nav with space switcher, context-sensitive sidebar, consistent design across all modules
  • REST API — full CRUD for tickets, wiki pages, projects, sprints, labels, and spaces

Self-Hosting

The fastest way to run Azimuthal is with Docker Compose:

# 1. Download compose file and environment template
curl -O https://raw.githubusercontent.com/Azimuthal-HQ/azimuthal/main/build/docker-compose.yml
curl -O https://raw.githubusercontent.com/Azimuthal-HQ/azimuthal/main/.env.example
cp .env.example .env

# 2. Edit .env — set passwords and generate a JWT secret
#    openssl rand -hex 32

# 3. Start everything
docker compose up -d

# 4. Create your first user
docker compose exec app /azimuthal admin create-user \
  --email admin@example.com \
  --name "Admin" \
  --password your-secure-password

See docs/self-hosting.md for the full guide including environment variable reference, backup/restore instructions, and troubleshooting.

Quick Start (from source)

Prerequisites
  • Go 1.23+
  • Node.js 20+ (for building the frontend)
  • PostgreSQL 15+
  • MinIO or S3-compatible storage (for file attachments)
Run locally
# 1. Clone and install tools
git clone https://github.com/Azimuthal-HQ/azimuthal.git
cd azimuthal
go install github.com/pressly/goose/v3/cmd/goose@latest

# 2. Start local services (postgres + minio)
docker compose -f build/docker-compose.dev.yml up -d

# 3. Set required env vars
export DATABASE_URL="postgres://azimuthal:dev@localhost:5432/azimuthal_dev?sslmode=disable"
export JWT_SECRET="$(openssl rand -hex 32)"

# 4. Run migrations
make migrate

# 5. Build and run
make build
./bin/azimuthal serve

The server starts on http://localhost:8080 by default.

CLI Commands

azimuthal serve                          Start the HTTP server
azimuthal backup --output file.tar.gz    Create a full backup
azimuthal restore --input file.tar.gz    Restore from backup
azimuthal admin create-user              Create a new user
azimuthal admin reset-password           Reset a user's password
azimuthal --version                      Show version
azimuthal --help                         Show all commands

Running Tests

make test

Tests run with the race detector and require CGO_ENABLED=1 (a C compiler must be available). On systems without GCC, run without the race detector:

go test ./...

Configuration

Variable Required Default Description
DATABASE_URL Yes — PostgreSQL connection string
JWT_SECRET Yes — Random 64-char string for JWT signing
APP_PORT No 8080 HTTP listen port
APP_ENV No development development, test, or production
STORAGE_ENDPOINT No — S3/MinIO endpoint
STORAGE_ACCESS_KEY No — S3/MinIO access key
STORAGE_SECRET_KEY No — S3/MinIO secret key
STORAGE_BUCKET No azimuthal Object storage bucket name
SMTP_HOST No localhost SMTP relay host
SMTP_PORT No 1025 SMTP relay port
LOG_LEVEL No info Log level (debug, info, warn, error)

Project Structure

cmd/server/        — single binary entrypoint (serves API + embedded frontend)
internal/core/     — all application logic
  api/             — HTTP handlers and router (chi)
  auth/            — authentication, JWT, sessions
  sso/             — SAML/OIDC single sign-on
  audit/           — append-only audit log
  rbac/            — role-based access control
  tickets/         — service desk module
  wiki/            — wiki/docs module
  projects/        — project tracking module
  storage/         — object storage interface
internal/db/       — database migrations and sqlc queries
internal/config/   — configuration loading
internal/jobs/     — background workers
web/               — React + TypeScript frontend (Vite, Tailwind, shadcn/ui)
migrations/        — goose SQL migration files
build/             — Dockerfile and docker-compose files

Contributing

See CONTRIBUTING.md for guidelines.

License

Apache 2.0 — see LICENSE for details.

Directories

Path Synopsis
cmd
migrate command
Package main provides a standalone migration runner for CI and deployment.
 Package main provides a standalone migration runner for CI and deployment.
server command
Package main is the single binary entrypoint for Azimuthal.
 Package main is the single binary entrypoint for Azimuthal.
docs
api
Package apidocs embeds the OpenAPI spec for inclusion in the binary.
 Package apidocs embeds the OpenAPI spec for inclusion in the binary.
internal
config
Package config loads and validates application configuration from environment variables.
 Package config loads and validates application configuration from environment variables.
core/analytics
Package analytics provides usage and performance reporting for Azimuthal.
 Package analytics provides usage and performance reporting for Azimuthal.
core/api
Package api wires all HTTP handlers together into a chi router and applies cross-cutting middleware.
 Package api wires all HTTP handlers together into a chi router and applies cross-cutting middleware.
core/api/auth
Package auth provides HTTP handlers for authentication endpoints.
 Package auth provides HTTP handlers for authentication endpoints.
core/api/comments
Package comments provides HTTP handlers for polymorphic entity comment endpoints.
 Package comments provides HTTP handlers for polymorphic entity comment endpoints.
core/api/notifications
Package notifications provides HTTP handlers for in-app notification endpoints.
 Package notifications provides HTTP handlers for in-app notification endpoints.
core/api/projects
Package projects provides HTTP handlers for project tracking endpoints.
 Package projects provides HTTP handlers for project tracking endpoints.
core/api/respond
Package respond provides shared JSON response helpers for HTTP handlers.
 Package respond provides shared JSON response helpers for HTTP handlers.
core/api/spaces
Package spaces provides HTTP handlers for space management endpoints.
 Package spaces provides HTTP handlers for space management endpoints.
core/api/tickets
Package tickets provides HTTP handlers for service desk endpoints.
 Package tickets provides HTTP handlers for service desk endpoints.
core/api/wiki
Package wiki provides HTTP handlers for wiki/docs endpoints.
 Package wiki provides HTTP handlers for wiki/docs endpoints.
core/api/workflows
Package workflows provides HTTP handlers for workflow engine endpoints.
 Package workflows provides HTTP handlers for workflow engine endpoints.
core/audit
Package audit defines the AuditLogger interface for recording structured, append-only audit events.
 Package audit defines the AuditLogger interface for recording structured, append-only audit events.
core/auth
Package auth provides local user authentication, JWT issuance, and HTTP middleware.
 Package auth provides local user authentication, JWT issuance, and HTTP middleware.
core/email
Package email provides the interface and implementations for sending email.
 Package email provides the interface and implementations for sending email.
core/notifications
Package notifications handles email and in-app alert delivery.
 Package notifications handles email and in-app alert delivery.
core/projects
Package projects implements project tracking: backlog, sprints, roadmap, and cross-tool item linking.
 Package projects implements project tracking: backlog, sprints, roadmap, and cross-tool item linking.
core/rbac
Package rbac provides role-based access control for Azimuthal.
 Package rbac provides role-based access control for Azimuthal.
core/sso
Package sso defines the SSOProvider interface for SAML/OIDC authentication.
 Package sso defines the SSOProvider interface for SAML/OIDC authentication.
core/storage
Package storage defines the ObjectStore interface and its implementations.
 Package storage defines the ObjectStore interface and its implementations.
core/tickets
Package tickets implements the service desk domain: ticket lifecycle, email ingestion/egress, and kanban board queries.
 Package tickets implements the service desk domain: ticket lifecycle, email ingestion/egress, and kanban board queries.
core/wiki
Package wiki implements wiki/docs: page tree, markdown rendering, version history, and conflict detection.
 Package wiki implements wiki/docs: page tree, markdown rendering, version history, and conflict detection.
core/workflow
Package workflow implements the workflow engine: state machines that govern how tickets and project items move through user-defined lifecycle states.
 Package workflow implements the workflow engine: state machines that govern how tickets and project items move through user-defined lifecycle states.
db
Package db manages database connectivity, migrations, and sqlc-generated queries.
 Package db manages database connectivity, migrations, and sqlc-generated queries.
db/adapters
Package adapters bridges the domain repository interfaces (auth, tickets, projects) to the sqlc-generated query layer.
 Package adapters bridges the domain repository interfaces (auth, tickets, projects) to the sqlc-generated query layer.
db/generated
jobs
Package jobs defines River-backed background workers for email and notifications.
 Package jobs defines River-backed background workers for email and notifications.
testutil
Package testutil provides shared helpers for integration tests.
 Package testutil provides shared helpers for integration tests.
Package migrations provides the embedded SQL migration files for Azimuthal.
 Package migrations provides the embedded SQL migration files for Azimuthal.
Package web embeds the built frontend assets into the Go binary.
 Package web embeds the built frontend assets into the Go binary.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.