Installation

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)
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

Set app.encryption_key in config.toml to a random 32-character string. See Encryption key.

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:

Set app.encryption_key to a random 32-character string. See Encryption key.
Set the db credentials and set db.host to localhost.
Set redis.address to localhost:6379.

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.

Install database tables

./libredesk --install

Creates the tables in PostgreSQL.

--install deletes existing libredesk data. Run it only on a new database.

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 1.25 or later
Node.js 20 or later
pnpm

Clone the repository

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

Build the application

make

Generates the libredesk binary in the current directory.

Configure libredesk

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

Edit config.toml:

Set app.encryption_key to a random 32-character string. See Encryption key.
Set the db credentials and set db.host to localhost.
Set redis.address to localhost:6379.

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

Creates the tables in PostgreSQL.

--install deletes existing libredesk data. Run it only on a new database.

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

Encryption key

app.encryption_key encrypts stored secrets such as inbox passwords. It must be exactly 32 characters. Generate one with openssl rand -hex 16. Set it before the first start and do not change it, or saved secrets can no longer be read.

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
`app.encryption_key = "..."`	`LIBREDESK_APP__ENCRYPTION_KEY=...`
`upload.fs.upload_path = "uploads"`	`LIBREDESK_UPLOAD__FS__UPLOAD_PATH=uploads`
`db.host = "localhost"`	`LIBREDESK_DB__HOST=localhost`

Command-line flags

Flag	Description
`--config`	Path to the config file. Defaults to `config.toml`
`--install`	Install the database schema
`--upgrade`	Run pending database upgrades
`--yes`	Skip the confirmation prompt
`--set-system-user-password`	Set the System user password
`--static-dir`	Directory with custom static files and templates
`--version`	Print the version

Rate limits

Public endpoints are rate limited per client IP. Change the limits in config.toml.

Section	Endpoints	Default (requests per minute)
`[rate_limit.widget]`	Livechat widget APIs	100
`[rate_limit.auth]`	Login, password reset and other auth endpoints	30
`[rate_limit.public]`	Help center, CSAT, `robots.txt` and sitemaps	100
`[rate_limit.media]`	Public media downloads (uploaded files, avatars)	300

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

Introduction

Getting Started

Configuration

Roles

Contributing

Installation methods

Docker installation

Quick start with Docker Compose

Binary installation

Compile from source

Encryption key

Configuration via environment variables

Command-line flags

Rate limits

Nginx reverse proxy (recommended)

​Installation methods

​Docker installation

​Quick start with Docker Compose

​Binary installation

​Compile from source

​Encryption key

​Configuration via environment variables

​Command-line flags

​Rate limits

​Nginx reverse proxy (recommended)

Installation methods

Docker installation

Quick start with Docker Compose

Binary installation

Compile from source

Encryption key

Configuration via environment variables

Command-line flags

Rate limits

Nginx reverse proxy (recommended)