Introduction

FlatRun is an open-source container management platform designed for developers, hobbyists, and small teams who want a simple yet powerful way to run Docker containers on their own infrastructure — without vendor lock-in.

Our Philosophy

We believe infrastructure should not be magical or locked-in. Too many server management tools hide your configuration in databases, proprietary formats, or obscure volume directories. This makes migrations painful and gives vendors leverage to increase prices — because leaving is hard.

Tools like Portainer store compose files in numbered folders inside volumes, making it difficult to understand or recover your setup. Control panels like Plesk have steadily increased prices over the years, knowing that migration is a nightmare for their users.

FlatRun takes a different approach:

• Flat Files — Everything lives on the filesystem in plain, readable directories
• Recognized Standards — Standard docker-compose.yml files you can use anywhere
• No Lock-in — Walk away anytime with docker compose up
• Full Transparency — No hidden databases, no magic, no surprises

What is FlatRun?

FlatRun consists of two main components:

• FlatRun Agent — A lightweight Go service that manages containers, handles SSL certificates, configures Nginx, and provides a REST API.
• FlatRun UI — A modern Vue.js dashboard for managing your containers through an intuitive interface.

Key Features

• Templates — Deploy popular applications like WordPress, Ghost, Laravel with pre-configured templates.
• Standard Docker Compose — Uses standard docker-compose files you already know.
• Automatic SSL — Let's Encrypt integration for automatic certificate provisioning and renewal.
• Reverse Proxy — Built-in Nginx integration for domain routing.
• Database Management — Manage MySQL, MariaDB, and PostgreSQL databases directly from the UI.
• Real-Time Monitoring — View container logs, resource usage, and health status.
• REST API — Full API access for automation and scripting.
• Self-Hosted — Run on your own server with complete control.

How it Works

FlatRun uses a simple filesystem-based approach. Each container stack is a directory with a standard docker-compose.yml file. The agent watches this directory and manages the container lifecycle.

/var/flatrun/
├── nginx/                    # Reverse proxy (managed by agent)
│   ├── conf.d/              # Virtual host configs
│   └── certs/               # SSL certificates
├── my-blog/                  # Your container stack
│   ├── docker-compose.yml   # Standard compose file
│   └── service.yml          # Optional: FlatRun metadata
└── my-api/                   # Another stack
    └── docker-compose.yml

When you create a container through the UI or API, the agent:

1. Creates the directory with your docker-compose.yml
2. Configures Nginx if you specify a domain
3. Obtains SSL certificates via Let's Encrypt
4. Runs docker compose up to start your containers

If you ever want to leave FlatRun, your containers keep running. Just use standard Docker commands — there's nothing proprietary to untangle.

Who is FlatRun For?

• Developers who want to self-host their side projects and applications.
• Small Teams looking for simple container management without Kubernetes complexity.
• Hobbyists running home servers or VPS instances.
• Agencies managing multiple client projects on dedicated servers.

Getting Help

If you run into issues or have questions:

• Check the Quick Start Guide for basic setup.
• Browse the documentation using the sidebar navigation.
• Report issues on GitHub Issues.
• View the source code on GitHub.