Self-hosted project management: deployment and operations guide

Self-hosted project management puts the application on infrastructure your organization operates. It gives you deployment control and responsibility for the service people depend on. Evaluate the choice by asking who will install, monitor, update, back up, and recover it, as well as where the data will live.

This guide explains the operational decisions behind self-hosted Leera. It uses the repository’s documented deployment as the product reference. Infrastructure examples are starting points, not capacity guarantees. Check the instructions for the release you intend to install before making production changes.

Decide what control you actually need

Write down the reason for self-hosting. It may be an existing infrastructure policy, a requirement to select a hosting region, integration with an internal network, or a desire to operate the complete application stack. A specific reason makes the trade-off easier to evaluate.

Then identify the service expectations. How long could the team work without the application? How much newly written data could it afford to reconstruct? Who responds if the server fails during a release? Those answers determine backup frequency, recovery preparation, and staffing more directly than the application’s installation time.

Neither column establishes compliance or availability on its own. If a contractual requirement drives the decision, verify the actual deployment and service terms that apply instead of treating a hosting label as proof.

Assign an operator before moving real work

Name a primary operator and a backup person. They need access to the server, domain configuration, backup location, and the team’s approved credential store. They also need time to perform maintenance.

Create an ownership note with the instance URL, deployment location, release version, support process, and recovery instructions. Keep enough of that note outside Leera that someone can find it while Leera is unavailable. The same applies to the credentials needed to restore the service.

Set an initial maintenance routine: inspect health, review backup completion, check disk growth, and review available updates. Give each action a responsible person and a clear result. “Operations owns it” becomes difficult to use when the person who installed the service is on leave.

For a trial, make the exit decision explicit. Decide what must be demonstrated before importing or recreating production work: successful login, required collaboration flows, file uploads, email behavior, backup restoration, and recovery ownership.

Understand the bundled deployment

Leera’s standard Compose deployment provides the web app, Rust API, a one-shot schema migrator, PostgreSQL, SeaweedFS object storage, and Caddy as the public reverse proxy. It does not require Redis or a separate managed PostgreSQL service.

The public README requires a Linux host with root or sudo access, at least 2 GB RAM, and 25 GB disk. Its AI-assisted provisioning example starts with 2 vCPU and 4 GB RAM. Measure the actual workload before sizing a larger service. Attachments, activity, database growth, and AI-related work can change resource needs.

Docker is not a prerequisite: the installer offers to install Docker Engine and the Compose plugin when they are absent. Organizations with a managed server baseline may prefer to install and configure Docker through that process first. Docker publishes its supported installation options in the Engine installation documentation.

Review Leera’s deployment overview, the instructions shipped with your release, and the installation script before executing it with administrative privileges. Record any changes from the supported configuration so future operators understand what they are maintaining.

Establish the public URL and HTTPS

Choose the hostname users will actually open and wait until its DNS A record resolves to the server before installation. Certificates are requested on first start; DNS that is still pending can cause that request to fail. The documented setup expects ports 80 and 443 to be available for the bundled reverse proxy. Use the same intended origin when completing the setup wizard, because it affects links and authentication redirects.

Caddy can obtain and renew certificates automatically when the deployment meets its requirements. DNS, network reachability, hostname choice, and challenge configuration matter; automatic HTTPS does not eliminate those prerequisites. Refer to Caddy’s HTTPS documentation when diagnosing certificate problems.

The bundled stack routes application requests through one public origin. The API, database, and object store stay on its internal network. If another reverse proxy already owns ports 80 and 443, use the installer’s external-proxy mode: bundled Caddy listens on 127.0.0.1:8080, and your proxy forwards every path to that address and terminates TLS.

Keep Leera’s routing in bundled Caddy instead of recreating individual paths in your proxy. Storage requests must keep their path prefix, AI streams must not be buffered, and routes can change between releases. The installer writes an nginx configuration for this arrangement. Follow the README’s external-proxy instructions, including certificate setup and the setup-wizard SSH tunnel. Inbound project email is not supported in external-proxy mode.

Install manually or with an AI agent

Once the server and DNS are ready, the public README’s manual installation command is:

curl -fsSL https://raw.githubusercontent.com/leera-app/leera-selfhost/main/install.sh | bash

The installer asks for a domain and offers to install Docker if needed. Enter a domain for automatic HTTPS; leave it blank only for local or LAN evaluation over plain HTTP. Everything is written to ~/leera by default, including the generated .env file containing instance secrets.

For an unattended install, replace pm.example.com with your prepared domain. LEERA_INSTALL_DOCKER=yes approves Docker installation if it is missing:

LEERA_DOMAIN=pm.example.com LEERA_INSTALL_DOCKER=yes bash -c "$(curl -fsSL https://raw.githubusercontent.com/leera-app/leera-selfhost/main/install.sh)"

Prefer an agent to handle the steps? Copy the complete AI installer prompt for an agent with terminal access. It covers AWS, GCP, an existing host, or local evaluation, with approval before paid resources or DNS changes. It asks you to authenticate in your own terminal, waits for DNS, runs the installer, checks HTTPS, and hands over backup and upgrade instructions.

Complete setup and verify the essential workflows

Open the URL printed by the installer and sign up immediately: the first account created becomes the instance administrator. Complete the initial setup wizard and confirm the instance URL. Manual core workflows work without registration. AI creation of issues, test cases and projects requires free registration and follows the instance license allowances. Standard Self Hosted uses Leera branding. White-label Self Hosted and Enterprise hide the Leera name and vendor links, apart from the sidebar’s desktop app download (server releases after 1.3.0), which names Leera Self-Hosted on every self-hosted plan once the desktop apps are released; the AI lotus icon stays the same across all plans. Custom branding follows the license entitlement in the current offering.

Use a small acceptance checklist before inviting the whole team:

1. Sign in and confirm the configured origin is correct.
2. Create a trial project and verify that another intended member can access it.
3. Create and update an issue, then check realtime behavior in another session.
4. Upload an attachment and verify that the appropriate member can retrieve it.
5. Create a document and review its access settings.
6. Check the email and AI workflows the team plans to use.
7. Take a backup and complete a separate-host restore drill.

The checklist should reflect your intended use. A team depending on QA needs to exercise a case, plan, run, and result. A team depending on external AI clients needs to test the actual client and authentication flow it will deploy.

Configure email and map external connections

Email deserves a deliberate setup step. In Leera’s documented behavior, notifications require configured SMTP. Standard Self Hosted can use the configured Leera relay for invitations and login codes when enabled and available; operators can configure their own mail service or refuse the fallback. White-label and Enterprise require instance SMTP and never use the Leera relay. Test the paths you intend to use.

Review sender configuration and delivery at the recipient’s mailbox, not just a successful test submission. Keep mail credentials in the instance’s supported settings and document who can rotate them. A working login for the initial administrator does not prove that future invitations will arrive.

Map every outbound dependency: mail, model providers, external AI clients, license or update services where used, storage alternatives, and any integrations you enable. The map should say what information is sent and why. Avoid describing a self-hosted deployment as having no external traffic until the actual configuration has been examined.

AI features need a configured provider and enabled model. The available setup controls depend on the installed version and administrator access. Core non-AI workflows do not become dependent on a model merely because the application offers AI assistance.

Treat the backup as a complete recovery set

A database dump alone is insufficient for a complete Leera recovery. Preserve the matching secret key and environment configuration with the database, and back up object storage for uploaded files. The secret key is required to decrypt stored credentials and preserve the corresponding authentication setup.

The documented backup command uses the default installation directory:

cd ~/leera && ./install.sh --backup

The backup directory includes leera.dump, secret_key, .env, version information, and a best-effort copy of storage/. Verify those outputs, including uploaded files. Copy the completed set to a separate protected location so a server failure does not remove both the application and its only backup. The installer keeps only the newest three backups on the server; plan off-server retention separately.

PostgreSQL supports logical backups while the database is in use; its SQL dump documentation explains the mechanism and its limits. Application recovery also depends on files and configuration outside PostgreSQL, so a successful database operation is only part of the check.

Define retention and access according to the information in the backup. Anyone who can read the matching environment and key material may have access to sensitive instance credentials. Keep backup access deliberate and ensure the recovery operator can obtain it when needed.

Prove recovery on a separate host

A restore drill is the most direct way to test whether the backup is usable. Prepare a separate host, follow the release-appropriate restore instructions, and restore a copied backup there. Do not test by replacing the only production instance.

On that recovery host, replace /path/to/backup with the copied backup directory:

cd ~/leera && ./install.sh --restore /path/to/backup

After restoration, verify login, representative projects, uploaded files, and configured credentials. If the API reports a secret-key mismatch, investigate whether the key and database were captured together. Do not regenerate a key and assume encrypted settings will become readable.

Record the steps, elapsed recovery time, missing prerequisites, and the location of the backup used. Have the backup operator repeat the exercise when practical. Recovery should depend on a procedure the team can follow, not on the installer remembering undocumented choices.

Use the result to adjust the plan. If restoring uploads takes longer than expected, the recovery estimate needs to include it. If the backup cannot be reached without a credential stored only inside the failed application, change the access arrangement.

Upgrade with a clear rollback decision

Review release information and verify your off-server backup before upgrading. The public README’s upgrade command takes a pre-upgrade backup, pulls new images, applies migrations, and restarts:

cd ~/leera && ./install.sh --upgrade

Keep disk headroom for both old and new images during an upgrade. The update refuses to start below 3 GB free and removes superseded images after a successful run. The optional updater can also support updates from Instance Settings. Its operational permissions include access to the host’s Docker socket; review the documented setup and disable that component if your operating policy requires command-driven updates.

Distinguish reverting application images from restoring data. An unhealthy upgrade can roll images back, but already applied database migrations are not automatically reversed. A data restore is a separate decision that can discard writes made after the backup.

Follow the backup and upgrade instructions shipped with the installed release. Database major-version upgrades need their own migration procedure; changing a container tag is not a complete migration plan.

Monitor the service within its supported shape

Monitor instance health, database and object-storage usage, certificate behavior, and backup results. Exercise a representative user path after a significant update. A process being alive does not establish that email, attachments, and collaboration all work.

Check the deployed version and container status:

cd ~/leera && ./install.sh --status

Follow the application logs when investigating failures:

cd ~/leera && docker compose logs -f api web

For an HTTPS check, replace pm.example.com with your hostname. Expect HTTP 200 without a TLS error, then open the application and verify the workflows your team needs:

curl -sS -o /dev/null -w '%{http_code}\n' https://pm.example.com

Keep the standard self-hosted API at one replica. Its realtime hub runs in process; multiple API containers need a shared event mechanism before they can distribute updates reliably. If higher availability is required, evaluate the architecture deliberately instead of adding replicas and assuming the result is equivalent.

Finally, review current pricing and deployment options alongside the operating cost. Hosting, provider usage, backup storage, maintenance time, and applicable licenses all belong in the comparison. A successful self-hosted deployment is one the team can continue to operate, recover, and understand after installation day.