Deploying Azimutt

Azimutt is a next-generation database exploration tool that brings modern ERD capabilities to real-world databases. Unlike traditional ERD tools that struggle with large schemas, Azimutt excels at visualizing databases with hundreds or thousands of tables—the kind you actually encounter in production environments.

Built with Elixir/Phoenix for the backend and Elm for the frontend, Azimutt provides a powerful yet intuitive interface for exploring, documenting, and analyzing any database schema, whether PostgreSQL, MySQL, SQL Server, MongoDB, or many others.

Smart Exploration

Display only relevant tables and follow relations intuitively

Schema Design

Design schemas using AML, Azimutt’s fast diagramming language

Documentation

Add notes, tags, and memos directly on tables and columns

Analysis Tools

Discover inconsistencies and get improvement suggestions

Key Features

Azimutt provides comprehensive database exploration capabilities:

Feature	Description
Multi-Database Support	PostgreSQL, MySQL, MariaDB, SQL Server, MongoDB, Couchbase, Oracle, SQLite
Smart Search	Find tables, columns, and relations across your entire schema
Selective Display	Show only the tables you need, hide everything else
Relation Following	Click to follow foreign keys and explore data relationships
Saved Layouts	Save different views for different use cases
Data Navigation	Query data and visualize results in the diagram
Schema Analysis	Get suggestions for naming, indexing, and structure improvements
AML Language	Design schemas quickly with Azimutt Markup Language

Why Azimutt?

Feature	Azimutt	Traditional ERD Tools
Large Schemas	Handles 1000+ tables smoothly	Becomes unusable at 50+
Selective View	Show only what matters	All-or-nothing display
Real Databases	Connects to live databases	Often import-only
Data Exploration	Query and visualize data	Schema only
Collaboration	Share layouts and documentation	Limited sharing
Self-Hosted	Full control on your infrastructure	Often cloud-only

Architecture Overview

Azimutt consists of several components:

Component	Purpose
Web Application	Elixir/Phoenix backend with Elm frontend
PostgreSQL	Stores projects, users, and organization data
File Storage	S3 or local storage for project JSON files
Email Service	Account validation and password reset
Gateway (Optional)	Node.js proxy for database connections

Note

The gateway component is optional. Users can connect to databases directly via the Azimutt CLI without deploying the gateway.

Prerequisites

Before deploying Azimutt on Klutch.sh, ensure you have:

• A Klutch.sh account with an active project
• A GitHub repository for your deployment
• A PostgreSQL database (can be deployed on Klutch.sh)
• S3-compatible storage (optional, can use local storage)

Project Structure

Set up your Azimutt deployment repository:

• Directoryazimutt/

  • Dockerfile
  • docker-compose.yml (local development only)
  • .env.example
  • README.md

Deployment Configuration

Dockerfile

Create a Dockerfile for your Azimutt deployment:

Dockerfile

FROM ghcr.io/azimuttapp/azimutt:main

# Set default port
ENV PORT=4000

# Expose the application port
EXPOSE 4000

Environment Variables

Azimutt requires several environment variables for proper configuration:

Required Variables

Variable	Description	Example
PHX_SERVER	Enable Phoenix server mode	true
PHX_HOST	Host of the deployed website	your-app.klutch.sh
PORT	Server port	4000
SECRET_KEY_BASE	Server encryption key (64+ bytes)	Random string
DATABASE_URL	PostgreSQL connection URL	postgresql://user:pass@host:5432/db
FILE_STORAGE_ADAPTER	Storage type (local or s3)	local
AUTH_PASSWORD	Enable email/password auth	true

Optional Database Configuration

Variable	Description	Default
DATABASE_IPV6	Use IPv6 for database	false
DATABASE_POOL_SIZE	Connection pool size	10
DATABASE_ENABLE_SSL	Require SSL connections	false

S3 Storage Configuration (if using S3)

Variable	Description
S3_BUCKET	S3 bucket name
S3_HOST	S3 host (if not using AWS)
S3_KEY_ID	S3 access key ID
S3_KEY_SECRET	S3 secret access key
S3_REGION	AWS region (default: eu-west-1)
S3_FOLDER	Folder within bucket (optional)

Email Configuration (Optional)

For SMTP email:

Variable	Description
EMAIL_ADAPTER	Set to smtp
SMTP_RELAY	SMTP server hostname
SMTP_USERNAME	SMTP username
SMTP_PASSWORD	SMTP password
SMTP_PORT	SMTP port

Tip

Email is optional for self-hosted deployments. You can set SKIP_EMAIL_CONFIRMATION=true to bypass email verification entirely.

Optional Feature Flags

Variable	Description
SKIP_ONBOARDING_FUNNEL	Skip onboarding for new users
SKIP_EMAIL_CONFIRMATION	Don’t require email verification
REQUIRE_EMAIL_ENDS_WITH	Restrict to specific email domain
ORGANIZATION_DEFAULT_PLAN	Default plan (free, solo, team, enterprise)
GLOBAL_ORGANIZATION	Add all users to this organization ID

Generating a Secret Key

Generate a secure SECRET_KEY_BASE:

# Using OpenSSL
openssl rand -base64 64

# Or using /dev/urandom
head -c 64 /dev/urandom | base64

Local Development with Docker Compose

Test your Azimutt setup locally:

docker-compose.yml

services:
  azimutt:
    image: ghcr.io/azimuttapp/azimutt:main
    ports:
      - "4000:4000"
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      - PHX_SERVER=true
      - PHX_HOST=localhost
      - PORT=4000
      - SECRET_KEY_BASE=${'{'}SECRET_KEY_BASE{'}'}
      - DATABASE_URL=postgresql://azimutt:azimutt@postgres:5432/azimutt
      - FILE_STORAGE_ADAPTER=local
      - AUTH_PASSWORD=true
      - SKIP_EMAIL_CONFIRMATION=true
    volumes:
      - azimutt_uploads:/app/bin/uploads

  postgres:
    image: postgres:16-alpine
    environment:
      - POSTGRES_DB=azimutt
      - POSTGRES_USER=azimutt
      - POSTGRES_PASSWORD=azimutt
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U azimutt -d azimutt"]
      interval: 5s
      timeout: 5s
      retries: 5

volumes:
  azimutt_uploads:
  postgres_data:

Create a .env.example file:

.env.example

# Generate with: openssl rand -base64 64
SECRET_KEY_BASE=your-64-byte-secret-key-here

Tip

Run docker compose up -d to start Azimutt locally. Access it at http://localhost:4000 and create your account with email/password authentication.

Deploying to Klutch.sh

Step 1: Deploy PostgreSQL Database

1. Create a PostgreSQL app on Klutch.sh

   1. Navigate to your Klutch.sh dashboard at klutch.sh/app
   2. Select your project or create a new one
   3. Click Create App and connect a repository with a PostgreSQL Dockerfile

   See our PostgreSQL deployment guide for detailed instructions.

2. Note your database connection details

   1. Record the internal hostname
   2. Note the database name, username, and password
   3. Construct your DATABASE_URL: postgresql://user:pass@hostname:5432/database

Step 2: Deploy Azimutt

1. Push your repository to GitHub

   1. Create a new repository with the Azimutt Dockerfile

   git init
   git add .
   git commit -m "Initial Azimutt configuration"
   git remote add origin https://github.com/yourusername/azimutt.git
   git push -u origin main

2. Create a new app on Klutch.sh

   1. Navigate to your Klutch.sh dashboard at klutch.sh/app
   2. Select your project
   3. Click Create App and connect your GitHub repository
   4. Klutch.sh will automatically detect your Dockerfile

3. Configure environment variables

   1. In your app settings, add the following environment variables

   Variable	Value
   PHX_SERVER	true
   PHX_HOST	your-app.klutch.sh
   PORT	4000
   SECRET_KEY_BASE	Your generated 64-byte key
   DATABASE_URL	Your PostgreSQL connection URL
   FILE_STORAGE_ADAPTER	local
   AUTH_PASSWORD	true
   SKIP_EMAIL_CONFIRMATION	true

   Caution

   Keep your SECRET_KEY_BASE secure! If compromised, attackers could forge sessions and access user data.

4. Configure the internal port

   1. Set the internal port to 4000
   2. Select HTTP as the traffic type

5. Set up persistent storage

   1. Add a persistent volume for local file storage

   Mount Path	Size
   /app/bin/uploads	10 GB

   Note

   The /app/bin/uploads directory stores project JSON files when using FILE_STORAGE_ADAPTER=local. Increase the size based on your expected number of projects.

6. Deploy your application

   1. Click Deploy to build and launch Azimutt
   2. Monitor the build logs for any issues
   3. Once deployed, your app will be available at https://your-app.klutch.sh

Initial Setup

After deployment, set up your Azimutt instance:

1. Create your account

   1. Visit https://your-app.klutch.sh
   2. Click Sign up or Get started
   3. Enter your email and password

2. Create an organization

   1. After signing up, create your organization
   2. This will be the container for your database projects

3. Create your first project

   1. Click New Project
   2. Choose how to import your schema (SQL file, database connection, or design from scratch)

Connecting to Databases

Azimutt supports multiple ways to explore your databases:

Option 1: Import SQL File

1. Export your schema

   1. Export your database schema to a SQL file

   # PostgreSQL
   pg_dump --schema-only -f schema.sql your_database
   
   # MySQL
   mysqldump --no-data your_database > schema.sql

2. Upload to Azimutt

   1. In your project, click Add source
   2. Select SQL file
   3. Upload your schema file

Option 2: Direct Database Connection

1. Use connection URL

   1. In your project, click Add source
   2. Select Database connection
   3. Enter your database connection URL

   postgresql://user:password@hostname:5432/database
   mysql://user:password@hostname:3306/database

2. Configure connection

   1. Choose which schemas/databases to include
   2. Click Connect to fetch the schema

   Note

   Direct connections work best with the Azimutt CLI or when the database is network-accessible from Azimutt.

Option 3: Design with AML

Create schemas from scratch using Azimutt Markup Language:

# Users table
users
  id uuid pk
  email varchar(255) unique
  name varchar(100)
  created_at timestamp

# Posts table with relation
posts
  id uuid pk
  user_id uuid fk users.id
  title varchar(255)
  content text
  published_at timestamp nullable

Using Azimutt

Exploring Your Schema

1. Search for tables

   1. Press / or click the search bar
   2. Type a table or column name
   3. Click to add it to your diagram

2. Follow relations

   1. Click on a foreign key column
   2. Select the related table to add it
   3. Relations are automatically drawn

3. Create layouts

   1. Arrange tables for a specific use case
   2. Save as a layout (e.g., “User Module”, “Orders Flow”)
   3. Switch between layouts instantly

Adding Documentation

Element	How to Document
Table Notes	Right-click table → Add note
Column Notes	Right-click column → Add note
Tags	Add tags to categorize tables
Memos	Add sticky notes anywhere on the canvas

Analyzing Your Schema

Azimutt provides analysis features:

• Naming Consistency: Find tables/columns with inconsistent naming
• Missing Indexes: Identify foreign keys without indexes
• Unused Tables: Find tables with no relations
• Schema Statistics: View table counts, column distributions

Using S3 Storage

For production deployments with multiple instances, use S3:

1. Create an S3 bucket

   1. Create a bucket in AWS S3, MinIO, or compatible service
   2. Configure bucket permissions for your access keys

2. Update environment variables

   1. Replace local storage configuration with S3

   Variable	Value
   FILE_STORAGE_ADAPTER	s3
   S3_BUCKET	Your bucket name
   S3_KEY_ID	Your access key ID
   S3_KEY_SECRET	Your secret access key
   S3_REGION	Your AWS region

GitHub SSO (Optional)

Enable GitHub authentication:

1. Create GitHub OAuth App

   1. Go to GitHub Settings → Developer settings → OAuth Apps
   2. Click New OAuth App
   3. Set Homepage URL to https://your-app.klutch.sh
   4. Set Callback URL to https://your-app.klutch.sh/auth/github/callback

2. Add environment variables

   1. Add GitHub OAuth credentials

   Variable	Value
   AUTH_GITHUB	true
   GITHUB_CLIENT_ID	Your OAuth client ID
   GITHUB_CLIENT_SECRET	Your OAuth client secret

Enterprise Features

For team deployments:

Variable	Description
ORGANIZATION_DEFAULT_PLAN	Set default plan for new organizations
GLOBAL_ORGANIZATION	Auto-add all users to one organization
GLOBAL_ORGANIZATION_ALONE	Hide other organizations (single-tenant mode)
REQUIRE_EMAIL_ENDS_WITH	Restrict to company domain (e.g., @company.com)

Security Best Practices

Secure Secrets

Use strong, randomly generated SECRET_KEY_BASE

HTTPS Only

Klutch.sh provides automatic SSL certificates

Email Domain

Use REQUIRE_EMAIL_ENDS_WITH for corporate deployments

Database SSL

Enable DATABASE_ENABLE_SSL in production

Troubleshooting

Common issues and solutions:

Issue	Cause	Solution
Database connection fails	Wrong DATABASE_URL	Verify connection string format and credentials
500 errors on startup	Missing SECRET_KEY_BASE	Generate and set a 64+ byte secret
Can’t upload files	Storage not configured	Check FILE_STORAGE_ADAPTER and volume mount
OAuth redirect fails	Wrong callback URL	Ensure PHX_HOST matches your deployment URL
Schema not loading	Database timeout	Increase DATABASE_POOL_SIZE

Checking Logs

Monitor your deployment through the Klutch.sh dashboard:

1. Navigate to your app
2. View deployment logs for startup issues
3. Check runtime logs for operational errors

Common Log Patterns

# Healthy startup
[info] Running AzimuttWeb.Endpoint with cowboy 2.x.x at :::4000
[info] Access AzimuttWeb.Endpoint at https://your-app.klutch.sh

# Database issues
[error] Postgrex.Protocol (#PID<x.x.x>) failed to connect: ** (DBConnection.ConnectionError)

Backup and Recovery

What to Back Up

Component	Location	Priority
PostgreSQL database	Your database server	Critical
Project files	/app/bin/uploads or S3	Important
Environment variables	Klutch.sh settings	Critical

Database Backup

# Export database
pg_dump -Fc your_database > azimutt_backup.dump

# Restore database
pg_restore -d new_database azimutt_backup.dump

Additional Resources

• Official Azimutt Documentation
• Azimutt GitHub Repository
• AML Language Documentation
• Full Installation Guide
• Database Schema Gallery
• Azimutt Slack Community