Installation

Deploy Libredesk using Docker, binary, or from source

Libredesk ships as a single binary and needs PostgreSQL and Redis to run. Install it with Docker, from a release binary, or from source.

Installation methods

Docker (Recommended)

Docker installation

The latest image is available on DockerHub at libredesk/libredesk:latest

Quick start with Docker Compose

1. Download configuration files

   # Download the compose file and the sample config file
   curl -LO https://github.com/abhinavxd/libredesk/raw/main/docker-compose.yml
   curl -LO https://github.com/abhinavxd/libredesk/raw/main/config.sample.toml
   
2. Configure Libredesk

   # Copy the config.sample.toml to config.toml and edit as needed
   cp config.sample.toml config.toml
   

   Edit config.toml with your database credentials and preferences.

3. Start the services

   # Run the services in the background
   docker compose up -d
   
4. Set the admin password

   # Set System user password
   docker exec -it libredesk_app ./libredesk --set-system-user-password
   

Visit http://localhost:9000 and login with:

• Email: System
• Password: The password you just set

Binary

Binary installation

Prerequisites:

• PostgreSQL ≥13
• Redis

1. Download the latest release

   Download the latest release for your platform and extract the libredesk binary.

2. Configure Libredesk

   # Download the sample config file
   curl -LO https://github.com/abhinavxd/libredesk/raw/main/config.sample.toml
   
   # Copy the config.sample.toml to config.toml and edit as needed
   cp config.sample.toml config.toml
   

   Edit config.toml with your database credentials and preferences.

3. Create the uploads directory

   With the default fs upload provider, files are stored in the directory set by upload.fs.upload_path (uploads, relative to the working directory). Libredesk does not create this directory, and uploads fail if it is missing or not writable.

   mkdir uploads
   chmod 755 uploads
   

   If Libredesk runs as a different user than the one that created the directory, give that user ownership with chown.

4. Install database tables

   ./libredesk --install
   

   Creates the tables in PostgreSQL.

   To set the System user password during installation, use the environment variable:

   LIBREDESK_SYSTEM_USER_PASSWORD=your_password ./libredesk --install
   
5. Set the System user password

   # Set System user password
   ./libredesk --set-system-user-password
   
6. Run Libredesk

   ./libredesk
   

Visit http://localhost:9000 and login with:

• Email: System
• Password: The password you just set

From Source

Compile from source

Build the latest unreleased version from the main branch.

Prerequisites:

• PostgreSQL ≥13
• Redis
• Go (latest version)
• Node.js (≥18)
• pnpm

1. Clone the repository

   git clone [e-mail]:abhinavxd/libredesk.git
   cd libredesk
   
2. Build the application

   make
   

   Generates the libredesk binary in the current directory.

3. Configure Libredesk

   # Download the sample config file
   curl -LO https://github.com/abhinavxd/libredesk/raw/main/config.sample.toml
   
   # Copy the config.sample.toml to config.toml and edit as needed
   cp config.sample.toml config.toml
   

   Edit config.toml with your database credentials and preferences.

4. Create the uploads directory

   With the default fs upload provider, files are stored in the directory set by upload.fs.upload_path (uploads, relative to the working directory). Libredesk does not create this directory, and uploads fail if it is missing or not writable.

   mkdir uploads
   chmod 755 uploads
   

   If Libredesk runs as a different user than the one that created the directory, give that user ownership with chown.

5. Install database tables

   ./libredesk --install
   

   Creates the tables in PostgreSQL.

   To set the System user password during installation, use the environment variable:

   LIBREDESK_SYSTEM_USER_PASSWORD=your_password ./libredesk --install
   
6. Set the System user password

   # Set System user password
   ./libredesk --set-system-user-password
   
7. Run Libredesk

   ./libredesk
   

Visit http://localhost:9000 and login with:

• Email: System
• Password: The password you just set

Configuration via environment variables

Instead of using a config.toml file, you can configure Libredesk entirely through environment variables.

• All environment variables use the LIBREDESK_ prefix
• Use double underscore (__) for nested configuration keys
• To use environment variables exclusively (without a config file), pass --config=""

Example:

TOML Config	Environment Variable
upload.fs.upload_path = "uploads"	LIBREDESK_UPLOAD__FS__UPLOAD_PATH=uploads
db.host = "localhost"	LIBREDESK_DB__HOST=localhost

Nginx reverse proxy (recommended)

We recommend running Libredesk behind Nginx as a reverse proxy.

Install nginx if you don’t have it:

# Debian / Ubuntu
sudo apt update && sudo apt install nginx

# RHEL / Fedora / CentOS
sudo dnf install nginx && sudo systemctl enable --now nginx

The proxy must set X-Client-IP to $remote_addr. Libredesk reads this header to identify the client for rate limiting and audit logs, and without it every request looks like it came from the proxy.

Save the following as /etc/nginx/sites-available/libredesk:

server {
    listen 80;
    server_name your-domain.com;
    client_max_body_size 30M;

    location / {
        proxy_pass http://localhost:9000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        
        proxy_set_header X-Client-IP $remote_addr;
        # If behind Cloudflare (or another CDN), forward the CDN's real-client header
        # instead, AND firewall nginx to only accept connections from the CDN's IP range,
        # otherwise clients can bypass the CDN and spoof this header directly.

        # proxy_set_header X-Client-IP $http_cf_connecting_ip;   # Cloudflare

        proxy_cache_bypass $http_upgrade;
    }
}

Then enable it and reload nginx:

sudo ln -s /etc/nginx/sites-available/libredesk /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx