Skip to main content

Try the live demo!

Search

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

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

Binary installation

Info:

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.

Warning:

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

Tip:

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

From Source

Compile from source

Build the latest unreleased version from the main branch.

Info:

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

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.

Warning:

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

Tip:

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

Warning:

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
Was this article helpful?