> ## Documentation Index
> Fetch the complete documentation index at: https://docs.libredesk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Deploy Libredesk using Docker, binary, or from source

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

## Installation Methods

<Tabs>
  <Tab title="Docker (Recommended)">
    ## Docker Installation

    The latest image is available on DockerHub at [libredesk/libredesk:latest](https://hub.docker.com/r/libredesk/libredesk)

    ### Quick Start with Docker Compose

    <Steps>
      <Step title="Download configuration files">
        ```bash theme={null}
        # 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
        ```
      </Step>

      <Step title="Configure Libredesk">
        ```bash theme={null}
        # 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.
      </Step>

      <Step title="Start the services">
        ```bash theme={null}
        # Run the services in the background
        docker compose up -d
        ```
      </Step>

      <Step title="Set the admin password">
        ```bash theme={null}
        # Set System user password
        docker exec -it libredesk_app ./libredesk --set-system-user-password
        ```
      </Step>
    </Steps>

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

    * **Email**: `System`
    * **Password**: The password you just set
  </Tab>

  <Tab title="Binary">
    ## Binary Installation

    <Info>
      **Prerequisites:**

      * PostgreSQL ≥13
      * Redis
    </Info>

    <Steps>
      <Step title="Download the latest release">
        Download the [latest release](https://github.com/abhinavxd/libredesk/releases) for your platform and extract the libredesk binary.
      </Step>

      <Step title="Configure Libredesk">
        ```bash theme={null}
        # 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.
      </Step>

      <Step title="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.

        ```bash theme={null}
        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`.
      </Step>

      <Step title="Install database tables">
        ```bash theme={null}
        ./libredesk --install
        ```

        This will create the necessary tables in PostgreSQL.

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

          ```bash theme={null}
          LIBREDESK_SYSTEM_USER_PASSWORD=your_password ./libredesk --install
          ```
        </Tip>
      </Step>

      <Step title="Set the System user password">
        ```bash theme={null}
        # Set System user password
        ./libredesk --set-system-user-password
        ```
      </Step>

      <Step title="Run Libredesk">
        ```bash theme={null}
        ./libredesk
        ```
      </Step>
    </Steps>

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

    * **Email**: `System`
    * **Password**: The password you just set
  </Tab>

  <Tab title="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
    </Info>

    <Steps>
      <Step title="Clone the repository">
        ```bash theme={null}
        git clone git@github.com:abhinavxd/libredesk.git
        cd libredesk
        ```
      </Step>

      <Step title="Build the application">
        ```bash theme={null}
        make
        ```

        This will generate the `libredesk` binary in the current directory.
      </Step>

      <Step title="Configure Libredesk">
        ```bash theme={null}
        # 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.
      </Step>

      <Step title="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.

        ```bash theme={null}
        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`.
      </Step>

      <Step title="Install database tables">
        ```bash theme={null}
        ./libredesk --install
        ```

        This will create the necessary tables in PostgreSQL.

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

          ```bash theme={null}
          LIBREDESK_SYSTEM_USER_PASSWORD=your_password ./libredesk --install
          ```
        </Tip>
      </Step>

      <Step title="Set the System user password">
        ```bash theme={null}
        # Set System user password
        ./libredesk --set-system-user-password
        ```
      </Step>

      <Step title="Run Libredesk">
        ```bash theme={null}
        ./libredesk
        ```
      </Step>
    </Steps>

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

    * **Email**: `System`
    * **Password**: The password you just set
  </Tab>
</Tabs>

## 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:

```bash theme={null}
# 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 uses this header to identify the client for rate limiting and audit logs. Without it, the proxy's IP is treated as the client.
</Warning>

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

```nginx theme={null}
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:

```bash theme={null}
sudo ln -s /etc/nginx/sites-available/libredesk /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
```