Install Legend

Legend runs as a Docker container with minimal resource requirements, and ships with an optional update agent container that powers in-app “Check for Updates”. Choose the installation method that matches your comfort level and infrastructure.

Not Interested in Self-Hosting?

Or let us host it for you. Managed hosting provisions a dedicated Legend instance for your organization, with backups, monitoring, and updates handled by the Legend team.

Prerequisites

Before installing, ensure you have:

• Operating system: Linux, macOS, or Windows with Docker support
• Docker: Version 20.10 or later (the install script handles this on Linux)
• Docker Compose: Version 2.0 or later (the install script handles this on Linux)
• Resources: 512MB RAM, 512MB disk space, 1 CPU core
• Network: Port 3000 available (or choose a different port during setup)
• Outbound connectivity: Required for license validation

Installation Methods

Install Script (Linux)

The install script is the recommended method for Linux users. It handles Docker installation, configuration, and deployment automatically.

Run the Install Script

curl -fsSL https://mylegend.io/install-legend.sh | bash

1. Check requirements: The script verifies curl, openssl, Docker, and Docker Compose are available. If Docker is missing, it offers to install it.
2. Interactive configuration: You are prompted for installation directory (default /opt/legend), host port (default 3000), optional domain or FQDN, storage type, and backup settings.
3. Generate secrets: A secure 64-character session secret is created using openssl rand -hex 32.
4. Create configuration: The script writes .env and docker-compose.yml files with your settings.
5. Pull and start: The Legend Docker image is pulled and the container starts.
6. Deploy the update agent: A small companion container is started alongside Legend to power in-app “Check for Updates”. It communicates with the Legend app over a shared Unix socket.
7. Health check: The script verifies the container is running and displays the access URL.

Storage Options

During installation, you choose between two storage configurations:

Single directory (recommended for most users): All data, including the SQLite database and YAML catalog, is stored in one location. This is simplest to manage and back up.

Separate storage: The YAML catalog is stored on an NFS or SMB mount, while the SQLite database remains on local SSD. This provides better performance for the database while allowing the catalog to be shared or version controlled.

Non-Interactive Mode

For automated deployments, set environment variables before running the script:

export LEGEND_INSTALL_DIR=/opt/legend
export LEGEND_HOST_PORT=3000
export LEGEND_DOMAIN=legend.example.com
export LEGEND_STORAGE_TYPE=single
export LEGEND_ENABLE_BACKUPS=true

curl -fsSL https://mylegend.io/install-legend.sh | bash

Available environment variables:

• LEGEND_INSTALL_DIR: Installation directory (default: /opt/legend)
• LEGEND_HOST_PORT: Host port to expose (default: 3000)
• LEGEND_DOMAIN: Optional domain or FQDN
• LEGEND_STORAGE_TYPE: single or separate (default: single)
• LEGEND_DATA_DIR: Path for YAML catalog (used with separate storage)
• LEGEND_DB_DIR: Path for SQLite database (used with separate storage)
• LEGEND_ENABLE_BACKUPS: Enable automated backups (default: true)
• LEGEND_UPDATE_AGENT_IMAGE: Update agent image reference (default: legendapp/legend-update-agent:latest)

What the Script Does

The install script handles Docker installation, configuration, and deployment automatically. It checks system requirements, generates secure secrets, creates configuration files, and starts the Legend container plus its update agent. Review the script behavior in the steps above before running.

Docker Compose

Docker Compose is ideal if you are comfortable with Docker and want explicit control over the configuration.

1. Create a directory for Legend:

   mkdir legend && cd legend

2. Generate a session secret:

   openssl rand -hex 32

   Copy the output. You need this 64-character string for the next step.

3. Create a .env file:

   cat > .env << EOF
   LEGEND_SESSION_SECRET=your-64-character-secret-here
   LEGEND_PUBLIC_APP_URL=http://localhost:3000
   LEGEND_DATA_DIR=/app/data
   LEGEND_DB_DIR=/app/data
   LEGEND_DB_FILENAME=legend.db
   LEGEND_PUBLIC_ENABLE_BACKUPS=true
   LEGEND_BACKUP_MAX_AGE_DAYS=30
   LEGEND_BACKUP_MIN_BACKUPS=5
   LEGEND_BACKUP_MAX_BACKUPS=100
   EOF

   Replace your-64-character-secret-here with the secret you generated. Update LEGEND_PUBLIC_APP_URL if you are using a domain or different port.

4. Prepare the update agent socket directory:

   sudo mkdir -p /etc/legend /var/run/legend-update
   echo "$(pwd)" | sudo tee /etc/legend/install-path > /dev/null

5. Create docker-compose.yml:

   cat > docker-compose.yml << EOF
   services:
     legend:
       image: legendapp/legend:latest
       container_name: legend
       ports:
         - "3000:3000"
       volumes:
         - ./data:/app/data
         - /var/run/legend-update:/var/run/legend-update
       env_file:
         - .env
       security_opt:
         - no-new-privileges:true
       restart: unless-stopped
   EOF

6. Create docker-compose.update-agent.yml:

   cat > docker-compose.update-agent.yml << EOF
   services:
     legend-update-agent:
       image: legendapp/legend-update-agent:latest
       container_name: legend-update-agent
       volumes:
         - /var/run/docker.sock:/var/run/docker.sock:ro
         - /var/run/legend-update:/var/run/legend-update
         - /etc/legend/install-path:/etc/legend/install-path:ro
       environment:
         - LEGEND_UPDATE_IMAGE=legendapp/legend:latest
       security_opt:
         - no-new-privileges:true
       restart: unless-stopped
   EOF

7. Create the data directory:

   mkdir data

8. Start Legend and the update agent:

   docker compose up -d
   docker compose -f docker-compose.update-agent.yml up -d

9. Verify the installation:

   docker compose ps
   curl http://localhost:3000

   You should see the Legend login page.

Session Secret Security

The session secret is used to sign JWT tokens and encrypt sensitive data. Use a strong, random value and never share it. If compromised, an attacker can forge authentication tokens.

Update Agent (Optional)

The update agent container is what powers the in-app “Check for Updates” button in the Admin panel. It requires read-only access to the Docker socket and the shared socket directory above. If you omit it, the app runs normally but the in-app update button reports the agent as unreachable; you can still update manually as shown below.

Docker Run

For minimal setups or testing, use a single docker run command.

1. Generate a session secret:

   openssl rand -hex 32

2. Create a data directory:

   mkdir -p legend-data

3. Prepare the update agent socket directory:

   sudo mkdir -p /etc/legend /var/run/legend-update
   echo "$(pwd)" | sudo tee /etc/legend/install-path > /dev/null

4. Run the container:

   docker run -d \
     --name legend \
     -p 3000:3000 \
     -v $(pwd)/legend-data:/app/data \
     -v /var/run/legend-update:/var/run/legend-update \
     -e LEGEND_SESSION_SECRET=your-64-character-secret-here \
     -e LEGEND_PUBLIC_APP_URL=http://localhost:3000 \
     -e LEGEND_PUBLIC_ENABLE_BACKUPS=true \
     --security-opt no-new-privileges:true \
     --restart unless-stopped \
     legendapp/legend:latest

   Replace your-64-character-secret-here with the secret you generated.

5. Run the update agent (optional):

   docker run -d \
     --name legend-update-agent \
     -v /var/run/docker.sock:/var/run/docker.sock:ro \
     -v /var/run/legend-update:/var/run/legend-update \
     -v /etc/legend/install-path:/etc/legend/install-path:ro \
     -e LEGEND_UPDATE_IMAGE=legendapp/legend:latest \
     --security-opt no-new-privileges:true \
     --restart unless-stopped \
     legendapp/legend-update-agent:latest

6. Verify the installation:

   docker ps
   curl http://localhost:3000

Environment Variables

For production deployments, use Docker Compose or the install script. They provide better configuration management and make updates easier.

Environment Variables Reference

All installation methods use the same environment variables. Here is what each one does:

Variable	Required	Default	Description
LEGEND_SESSION_SECRET	Yes	None	64-character hex string for JWT signing and encryption. Generate with openssl rand -hex 32.
LEGEND_PUBLIC_APP_URL	No	http://localhost:3000	The URL where Legend is accessible. Used for links and redirects.
LEGEND_DATA_DIR	No	/app/data	Path inside the container for YAML catalog, documentation, and branding.
LEGEND_DB_DIR	No	/app/data	Path inside the container for the SQLite database. Separate from LEGEND_DATA_DIR for performance.
LEGEND_DB_FILENAME	No	legend.db	SQLite database filename.
LEGEND_PUBLIC_ENABLE_BACKUPS	No	true	Enable automated daily backups at 2 AM.
LEGEND_BACKUP_MAX_AGE_DAYS	No	30	Delete backups older than this many days.
LEGEND_BACKUP_MIN_BACKUPS	No	5	Always keep at least this many backups, even if older than max age.
LEGEND_BACKUP_MAX_BACKUPS	No	100	Maximum number of backups to retain.
LEGEND_LICENSE_SERVER_URL	No	https://mylegend.io	License server URL. Only change if using a custom license server.
LEGEND_UPDATE_AGENT_IMAGE	No	legendapp/legend-update-agent:latest	Update agent image reference used by the install script. Only change if you mirror the agent image.

Verify the Installation

After installation, verify Legend is running:

1. Check the container:

   docker ps | grep legend

   You should see the Legend container running.

2. Access the web interface: Open your browser and navigate to http://localhost:3000 (or your configured domain).

3. Complete the setup wizard: On first visit, you are redirected to the setup wizard where you create the initial administrator account.

What Happens Next

After installation, the setup wizard guides you through creating your admin account. Then the onboarding wizard helps you populate Legend with demo data and common services. See the First Steps guide for details.

Update Legend

To update Legend to the latest version, use the methods below. See Updates and Version Management for the complete update guide, including managed hosting behavior.

In-App Updates (Recommended)

If you deployed the update agent (install script does this automatically), use the Check for Updates button in the Admin panel. Legend asks the update agent to pull the latest image, recreate the container preserving your configuration, and verify health. If the update fails, the agent rolls back to the previous image automatically.

Manual Updates

Install Script

cd /opt/legend
docker compose pull
docker compose up -d

Docker Compose

cd legend
docker compose pull
docker compose up -d

Docker Run

docker stop legend
docker rm legend
docker run -d \
  --name legend \
  -p 3000:3000 \
  -v $(pwd)/legend-data:/app/data \
  -v /var/run/legend-update:/var/run/legend-update \
  -e LEGEND_SESSION_SECRET=your-64-character-secret-here \
  -e LEGEND_PUBLIC_APP_URL=http://localhost:3000 \
  --security-opt no-new-privileges:true \
  --restart unless-stopped \
  legendapp/legend:latest

Your data is persisted in the mounted volume, so updates do not affect your configuration or entities.