Self-hosting tlDiagram for local architecture work

“Self-hosting” can describe a private team service or simply running a local instance on your workstation. Those are different operating choices. The open-source tld project supports local operation through its CLI and web editor, and documents Docker Compose configurations for a more persistent deployment. Pick the smallest setup that fits the work.

Start with the local server

For an individual architecture task, install the tld CLI and run tld serve. The documented default is a web editor at http://127.0.0.1:8060, bound to loopback, with an embedded SQLite database. The server can run in the background; tld status checks it and tld stop shuts it down. This is a straightforward way to inspect and edit diagrams without deploying an always-on service.

tld serve
# Open http://127.0.0.1:8060
tld status

Local operation stores the server's database and logs in its data directory. The documentation identifies ~/.local/share/tldiagram/ as the default and allows an alternate path with --data-dir or TLD_DATA_DIR. Configuration is kept separately in the user's config directory. Back up the data directory if it holds work you cannot recreate.

Local does not automatically mean a YAML workspace is present. A project can have an optional .tld/ directory containing version-controlled configuration, elements, connectors, and sync metadata. Without a workspace, commands use the configured database target. Run tld context and understand the selected target before editing: current CLI behavior can choose a cloud target when cloud credentials are configured and the target is left on auto.

Keep local data local by choice

The local server itself does not require a cloud account for local editing. Commands that synchronize or apply changes to a remote target are separate operations. If you need a strictly local workflow, use the local target intentionally and do not run remote sync or apply commands. A local workspace in Git gives teammates a reviewable source form, but it is not the same thing as a shared live service.

Use containers for a persistent deployment

The repository includes a SQLite Compose stack and a PostgreSQL Compose stack. From a checkout, the documented commands are:

# SQLite
  docker compose up -d

# PostgreSQL
docker compose -f docker-compose.postgres.yml up -d

Both examples expose the UI at 127.0.0.1:8060 by default and store data in named volumes. PostgreSQL uses the standard postgres:16 image without required extensions. Review the Compose files before adapting them: the published endpoint, volume retention, secrets, and network exposure should match your own environment.

For a non-container deployment, tld serve can use PostgreSQL by configuring database.driver and database.url in global configuration or environment variables. The README documents TLD_DB_DRIVER and TLD_DATABASE_URL. When placed behind a reverse proxy, set the public URL appropriately; TLD_HOST controls the bind address. The docs recommend tld serve --foreground when a service manager should supervise the process.

Plan operations, not just installation

A team instance needs ordinary service ownership: someone must manage upgrades, backups, restore checks, logs, credentials, and network access. SQLite is convenient for a local or modest single-instance setup; PostgreSQL is available when your deployment needs a separate database service. The project documentation describes both options, but does not remove the need to size, secure, and operate your own infrastructure.

Decide how people will collaborate. A local database belongs to the machine running it. A committed YAML workspace can be reviewed through Git and synchronized deliberately. A self-hosted web service provides a shared endpoint, but your team remains responsible for how it is exposed and maintained. These are complementary patterns, not interchangeable labels.

Choose the workflow that fits

Use tld serve when you want a quick local editor close to a repository. Add a YAML workspace when you want architecture changes alongside code review. Use the supplied Compose configuration or a PostgreSQL-backed service when you need a persistent deployment under your control. Keep target selection explicit, and document where the source of truth lives before multiple people begin editing.

That clarity makes the setup easier to reason about: engineers know where their diagram data is stored, what commands can send it elsewhere, and which operational responsibilities accompany a shared service.