Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/flancian/garden/llms.txt

Use this file to discover all available pages before exploring further.

Running your own Agora gives you full control over which gardens are included, how content is served, and how your instance integrates with social platforms. The Agora is composed of three separate repositories that work together: a configuration root, a read-oriented web server, and a write-oriented bridge that ingests content from external sources.

​
Architecture overview

agora

The Agora root: gardens.yaml source list, CONTRACT.md, and the tree configuration. Think of it as the fstab of your Agora.

agora-server

A Python/Flask web interface that renders the Agora as a distributed knowledge graph. Mostly read-only.

agora-bridge

The write-side component. Pulls content from all configured sources, runs bots, and handles social media integrations.
There is currently no Docker support. All three services run directly on the host as a Unix user. Docker support is planned — contributions are welcome.

​
Prerequisites

  • A Unix-like system (Debian GNU/Linux is what anagora.org runs)
  • Python 3, git, nginx, and certbot installed
  • A domain name pointed at your server if you want public HTTPS access

​
Setup

1

Create a dedicated user

All repositories and services run under a single Unix user. The reference deployment uses agora:
adduser agora   # follow the prompts
sudo su - agora
2

Clone all three repositories

From the agora user’s home directory, clone all three repos:
git clone https://github.com/flancian/agora.git
git clone https://github.com/flancian/agora-server.git
git clone https://github.com/flancian/agora-bridge.git
You need all three for a fully functioning Agora. Technically you can run only agora-server for a read-only, static view, but the setup below covers the full stack.
3

Configure your source list

Open agora/gardens.yaml (sometimes called sources.yaml) and edit the list of gardens your Agora will include. The repository ships with defaults from the reference Agora at anagora.org.
# agora/gardens.yaml — example structure
- url: https://github.com/flancian/garden
  format: markdown
- url: https://github.com/example/their-garden
  format: markdown
gardens.yaml is the fstab of your Agora — it declares every content source the bridge will pull from and the server will render.
4

Review CONTRACT.md

agora/CONTRACT.md contains the system account’s public commitment to the ecosystem. You can read and keep it as-is. If you modify it, your Agora may become incompatible with the one you forked from — conflict resolution is part of the Agora Protocol but is not yet fully specified.
5

Set up agora-server

agora-server is a Python/Flask application. Create a virtual environment, install dependencies, and run the provided setup script:
cd agora-server
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
./setup.sh
If your repos are not in the default path /home/<user>/<repo>, edit app/config.py to reflect your actual paths.To verify the server works locally:
./run-dev.sh
6

Run agora-server in production with UWSGI and nginx

For public-facing deployments, use run-prod.sh which starts the server over a UWSGI socket:
./run-prod.sh
Issue a TLS certificate with Certbot:
certbot --nginx -d example.anagora.org
Add the following location block to your nginx virtual host to forward traffic to the UWSGI socket:
location / {
    include uwsgi_params;
    # /home/agora/agora-server/run-prod.sh to run.
    uwsgi_pass unix:/tmp/agora-uwsgi.sock;
}
To keep the server running across reboots, register it as a systemd service using the agora-server.service example included in the repository.
7

Set up agora-bridge

agora-bridge handles all content ingestion. Set it up the same way as the server:
cd agora-bridge
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
./setup.sh
Then start the bridge:
./run-prod.sh
This pulls from every source listed in agora/gardens.yaml in a continuous loop. Run it as a systemd service for persistence.

​
What’s next

Configure Agora Bridge

Learn how to configure bridges.yaml, add sources, and set up per-user agora.yaml files.

Bots and integrations

Connect your Agora to Mastodon, Twitter, and Matrix using the built-in bots.
Once your Agora is running, consider reviewing the Agora Protocol and reaching out to the community if you are interested in establishing inter-Agora collaboration protocols.

Build docs developers (and LLMs) love

Get started for freeTalk to us