Introduction

Makiatto is a lightweight, self-hosted CDN (Content Delivery Network) that lets you deploy and distribute content across multiple servers with minimal infrastructure overhead.

It creates a secure WireGuard mesh network between your machines and provides automatic content synchronisation across all nodes, GeoDNS routing to direct users to their nearest server, coordinate-based geographic distribution through simple CLI commands, and built-in SSL certificate management via Let's Encrypt.

Makiatto is simple - one-command deployment with no complex configurations or control planes. Just run makiatto-cli machine init to add a node and makiatto-cli sync to deploy content. It's decentralised with no single point of failure - each node operates independently while staying in sync through a distributed consensus mechanism. And it's completely self-hosted, giving you full control over your infrastructure with no vendor lock-in, no surprise bills, and no data leaving your servers.

Ready to get started? Head to the Getting Started guide to install Makiatto and set up your first CDN node.

Installation

There are several ways to install the Makiatto CLI on your local machine.

Using Cargo

If you have Rust installed, you can install directly from crates.io:

cargo install makiatto-cli

If you don't have Rust installed, get it from rustup.rs.

Download from GitHub Releases

You can download pre-built binaries from the releases page.

Choose the correct file for your platform:

• makiatto-cli-x86_64-unknown-linux-gnu.tar.gz - Linux (Intel/AMD)
• makiatto-cli-aarch64-unknown-linux-gnu.tar.gz - Linux (ARM64)
• makiatto-cli-x86_64-apple-darwin.tar.gz - macOS (Intel)
• makiatto-cli-aarch64-apple-darwin.tar.gz - macOS (Apple Silicon)

Then extract and install:

tar -xzf makiatto-cli-*.tar.gz
chmod +x makiatto-cli
mv makiatto-cli /usr/local/bin/

Verify installation

After installation, verify everything is working:

makiatto-cli --version

Getting Started

This guide will walk you through setting up your first CDN nodes with Makiatto.

Prerequisites

You'll need servers to run your CDN nodes. These can be VPS instances, dedicated servers, or cloud VMs. Each server should have:

• A public IPv4 address (IPv6 is recommended but optional)
• A supported Linux distribution (Ubuntu, Debian, or similar)
• SSH access (any port)
• These ports open:
  • 53 (DNS)
  • 80 (HTTP)
  • 443 (HTTPS)
  • 853 (DNS over TLS)
  • 51820 (WireGuard)

Make sure you have the Makiatto CLI installed on your local machine. See the Installation guide if you haven't done this yet.

Setting up your first nodes

Initialise your CDN nodes with the machine init command. This will install the Makiatto daemon on each server and configure them to join the mesh network:

makiatto-cli machine init vector root@203.0.113.1
makiatto-cli machine init klukai ubuntu@198.51.100.1
makiatto-cli machine init tololo admin@192.0.2.1

The command format is makiatto-cli machine init <name> <user>@<ip>. These names will be used as nameserver hostnames (e.g., vector.ns.example.com), so choose something short and meaningful.

You can verify your nodes are connected:

makiatto-cli machine list

Creating your project configuration

Create a makiatto.toml file in your project directory:

[[domain]]
name = "example.com"
path = "./dist"

This tells Makiatto which domain to serve and where your static files are located. The path is relative to the makiatto.toml file.

Deploying content

With your nodes set up and configuration ready, deploy your content:

makiatto-cli sync

This command syncs your static files and domain configuration to all nodes in the mesh. Your content is now distributed globally!

DNS setup

For GeoDNS routing to work, you need to configure your domain to use Makiatto's nameservers:

makiatto-cli dns nameserver-setup

This command will output detailed instructions like this:

Follow these steps to configure your custom nameservers:

:: Step 1: Add glue records to your domain registrar

Glue records tell the internet where to find your nameservers when they're subdomains of your own domain.
Without them, there's a circular dependency: DNS can't find your nameservers to resolve your domain.
Add these as glue records (also called 'name server records' or 'host records') in your domain registrar's control panel.

:: Glue records for example.com:

  vector.ns.example.com: 203.0.113.1, 2001:db8::1
  klukai.ns.example.com: 198.51.100.1, 2001:db8::2
  tololo.ns.example.com: 192.0.2.1, 2001:db8::3

:: Step 2: Set your domain to use your custom nameservers

After adding glue records, you must also tell your registrar to use your custom nameservers instead of their defaults.
In your domain registrar's control panel, change the nameservers for your domain to:

:: Nameservers for example.com:

  vector.ns.example.com
  klukai.ns.example.com
  tololo.ns.example.com

:: Step 3: Testing and verification
After configuration, test your setup with:

  dig @vector.ns.example.com example.com

Note: DNS changes may take 24-48 hours to propagate globally.

Once DNS propagates, visitors will be automatically routed to their nearest node.

What's next?

Your CDN is now operational! Check out the Usage Guide for more advanced features like managing multiple domains, updating content, and monitoring your nodes.

Usage Guide

This guide covers the core commands and workflows for managing your Makiatto CDN.

Machine Management

List all configured machines in your profile:

makiatto-cli machine list

Add an existing Makiatto node to your profile:

makiatto-cli machine add <user@host>

Upgrade Makiatto binary on machines:

makiatto-cli machine upgrade [machine names...]

If no machine names are provided, all machines will be upgraded. You can optionally specify --binary-path to use a local binary instead of downloading from GitHub releases.

Remove a machine from the cluster:

makiatto-cli machine remove <machine-name>

This command will:

• Remove the machine from all peer databases in the cluster
• Stop and disable the makiatto service on the target machine
• Clean up all makiatto files and directories (/var/makiatto, /etc/makiatto)
• Remove the makiatto binary and user
• Update your profile configuration

You'll be prompted for confirmation before removal. Use --force to skip the confirmation prompt:

makiatto-cli machine remove <machine-name> --force

Status

Check cluster health:

makiatto-cli health

The health command performs comprehensive checks across your entire cluster.

Configuration

Your project configuration lives in makiatto.toml. Here's a complete example:

[[domain]]
name = "example.com"
path = "./dist"
aliases = ["www.example.com", "old-domain.com"]

[[domain.records]]
type = "TXT"
name = "_dmarc"  # Creates _dmarc.example.com
value = "v=DMARC1; p=none; rua=mailto:dmarc@example.com"

[[domain.records]]
type = "MX"
name = "@"  # @ means the root domain (example.com)
value = "mail.example.com"
ttl = 300
priority = 10

Required fields

• name - The domain name to serve
• path - Path to static files (relative to makiatto.toml)

Optional fields

aliases - Domains that CNAME to your site. When external domains point to your Makiatto domain via CNAME, listing them here tells Makiatto to:

• Obtain SSL certificates for them
• Serve your content when visitors access them
• Common uses: www subdomains, alternative domain names

domain.records - Custom DNS records to add. Useful for:

• Email configuration (MX, SPF, DKIM)
• Domain verification (TXT)
• Subdomains pointing elsewhere
• Custom records beyond what Makiatto auto-creates

Automatic DNS records

Makiatto automatically creates:

• A/AAAA records for your domain (with GeoDNS)
• NS records for your nameservers
• SOA record for the zone
• CAA record for Let's Encrypt

Multiple domains

You can configure multiple domains in one file:

[[domain]]
name = "example.com"
path = "./dist/blog"

[[domain]]
name = "zuccherocat.cafe"
path = "./dist/site"

Profile Management

Your machine configuration is stored in a profile (default: ~/.config/makiatto/default.toml). Profiles can be stored anywhere - in your home directory for personal use or in your project repository for team sharing:

# Personal profile in home directory
makiatto-cli --profile ~/.config/makiatto/zucchero.toml machine list

# Shared profile in project repo
makiatto-cli --profile ./deployment/zucchero.toml sync

You can also set the MAKIATTO_PROFILE environment variable:

export MAKIATTO_PROFILE=./deployment/defy.toml
makiatto-cli sync

The --profile flag takes precedence over the environment variable when both are set.

FAQ

Why does Makiatto use GeoDNS instead of anycast?

Commercial CDN providers use anycast routing where the same IP address is announced from multiple locations, and internet routing protocols direct users to the nearest server. While this is elegant, it requires:

• Owning IP address blocks (expensive and requires justification)
• BGP peering agreements with multiple ISPs
• Infrastructure in internet exchange points
• Significant technical expertise and relationships

GeoDNS achieves similar results by using GPS coordinates to determine which server is closest to each user. This approach works with regular VPS providers and doesn't require any special infrastructure, making it perfect for self-hosters and small teams who want CDN functionality without enterprise-level requirements.

Can I use Makiatto with an existing web server?

Currently, Makiatto includes its own web server that listens on ports 80 and 443. It's designed to be the primary web server for your domains.

If you have an existing web server (like nginx or Apache) on the same machine, you would need to:

• Run your existing server on different ports (e.g., 8080/8443), or
• Use dedicated machines for Makiatto (recommended)

Future versions may support reverse proxy configurations, but for now Makiatto expects to own ports 80/443.

Can I host dynamic content or is it only for static files?

Makiatto is currently designed for static content distribution. It syncs files from your local path directory to all nodes and serves them directly.

For dynamic content, you have a few options today:

• Use Makiatto for your static assets (JS, CSS, images) while keeping your dynamic app on a separate domain
• Use static site generators to pre-build your dynamic content into static files

However, WebAssembly support is planned for the future! This will allow you to:

• Transform content on-the-fly with WebAssembly filters (similar to nginx filter modules)
• Deploy serverless functions like Cloudflare Workers
• Build dynamic applications that run on all your CDN nodes

Until then, the focus on static content is what keeps Makiatto simple and efficient - there's no need to worry about session state, database replication, or cache invalidation across nodes.