Skip to main content
LibredeskLibredesk
Search

Installation

Deploy Libredesk using Docker, binary, or from source

Abhinav Raut · Last updated

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

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

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

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 (latest version)
  • Node.js (≥18)
  • pnpm

Clone the repository

git clone [email protected]:abhinavxd/libredesk.git
cd libredesk

Build the application

make

Generates 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

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.

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

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

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?