Installation

Libredesk is a single binary application that requires postgres and redis to run. You can install it using the binary or docker.

Installation Methods

Docker (Recommended)
Binary
From Source

Docker Installation

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

Quick Start with Docker Compose

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

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.

Start the services

# Run the services in the background
docker compose up -d

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 Installation

Prerequisites:

PostgreSQL ≥13
Redis

Download the latest release

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

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.

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 - file 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.

Install database tables

./libredesk --install

This will create the necessary tables in PostgreSQL.

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

LIBREDESK_SYSTEM_USER_PASSWORD=your_password ./libredesk --install

Set the System user password

# Set System user password
./libredesk --set-system-user-password

Run Libredesk

./libredesk

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

Email: System
Password: The password you just set

Compile from Source

Build the latest unreleased version from the main branch.

Prerequisites:

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

Clone the repository

git clone git@github.com:abhinavxd/libredesk.git
cd libredesk

Build the application

make

This will generate the libredesk binary in the current directory.

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.

Create the uploads directory

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.

Install database tables

./libredesk --install

This will create the necessary tables in PostgreSQL.

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

LIBREDESK_SYSTEM_USER_PASSWORD=your_password ./libredesk --install

Set the System user password

# Set System user password
./libredesk --set-system-user-password

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 Configuration (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 uses this header to identify the client for rate limiting and audit logs. Without it, the proxy’s IP is treated as the client.

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

Introduction

Getting Started

Configuration

Roles

Contributing

Installation Methods

Docker Installation

Quick Start with Docker Compose

Binary Installation

Compile from Source

Configuration via Environment Variables

Nginx Configuration (Recommended)

​Installation Methods

​Docker Installation

​Quick Start with Docker Compose

​Binary Installation

​Compile from Source

​Configuration via Environment Variables

​Nginx Configuration (Recommended)

Installation Methods

Docker Installation

Quick Start with Docker Compose

Binary Installation

Compile from Source

Configuration via Environment Variables

Nginx Configuration (Recommended)