# Installing RevDeBug server

## Prerequisites

RevDeBug server is distributed in the form of docker images that can be easily deployed using a docker-compose utility.

More detailed information about the installation and preparation of the Docker environment and Docker Compose can be found here:

* [https://docs.docker.com/engine/install/ ](<https://docs.docker.com/engine/install/ >)
* <https://docs.docker.com/compose/install/>

RevDeBug requires:

1. Docker-compose version >= 1.29.0
2. Ability to pull docker images from docker.revdebug.com on the server

## Requirements & Architecture

You need a separate working environment (physical or virtual machine), on which the RevDeBug server containers will run using docker-compose.

![RevDeBug Server-side architecture](/files/55WkRs3QKNjMzhyhpU9p)

1. **Container services:**
   * Web interface
   * Reverse proxy (Nginx) for the web interface
   * Endpoint of the recording stream
   * Endpoint for continuous transmission of performance metrics
   * PostgreSQL database (provided but shared instance can be used as well)
   * OpenSearch RESTful search engine<br>

2. **Hardware requirements for the server :**

   * CPU: 4x vCore (corresponding to i7 3GHz+)
   * RAM: 32 GB RAM
   * Volumes (disk space): 500GB+ on SSD
   * Network interface: Wired LAN Gigabit Ethernet

3. **Open TCP/IP ports:**
   * 42733 - 42735 (streaming of recordings and compilation metadata)
   * 11800 (connection for continuous transfer of memory and CPU usage statistics for JVM)
   * HTTP/HTTPS (web interface)<br>

4. **RevDeBug requires access from the server to:**

   * Source code repository (login via dedicated user and password with read-only permissions to the repositories recommended)
   * Ability to pull docker images from docker.revdebug.com on the server

5. **The following services must have network access to the RevDeBug server:**
   * CI/CD server/build-agents\
     (communication from the CI/CD server building process to RevDeBug server to transfer compilation time metadata - connection on port 42734)

## **Get a license**

You need to obtain a license to use RevDeBug. Please contact us a&#x74;**:**

<mark style="color:blue;"><sales@revdebug.com></mark>

## Setting up RevDeBug Server instance

To set up a RevDeBug Server instance clone docker-compose project from the public git repository to your virtual machine or physical server:

```bash
git clone https://github.com/RevDeBug/revdebug-server-docker-compose
cd revdebug-server-docker-compose
```

Next in the cloned directory copy the template of the settings file holding environment variables for docker-compose and name it ".env":

```bash
cp .env-template .env
```

Variables needed to be set up (other settings are optional):

* **`REVDEBUG_SERVER_NAME`** - fully qualified DNS server name or IP address ie.: *servername.your.domain.com*
* **`REVDEBUG_AUTH_OPENID_SECRET`** - A secret used within an authentication service provider. The key can be any string of characters. To generate it, you can use the command below (it needs to be 32 alphanumeric characters, dashes are also allowed):

{% tabs %}
{% tab title="Bash" %}

```bash
tr -dc A-Za-z0-9 </dev/urandom | head -c 32 ; echo ''
```

{% endtab %}

{% tab title="Python" %}

```python
python3 -c 'import uuid;print(str(uuid.uuid4()))'
```

{% endtab %}
{% endtabs %}

* **`KEYCLOAK_USER`**- admin user for keycloak admin&#x20;
* **`KEYCLOAK_PASSWORD`**- admin user password for keycloak change\_me\_in\_env\_file

Those variables are stored on the first server deployment, if you have set them up incorrectly or want to change them please read the [troubleshooting section](#troubleshooting) below.

All docker-compose commands should be run from the inside of a previously cloned directory.

Usually, docker-compose commands are executed using the `sudo` command.

To pull the latest docker images execute:

{% tabs %}
{% tab title="Default" %}

```bash
sudo docker compose -p revdebug pull
```

{% endtab %}

{% tab title="Standalone" %}

```bash
sudo docker-compose -p revdebug pull
```

{% endtab %}
{% endtabs %}

### Adding a secure connection to the Revdebug server

Description of adding a [secured ssl connection](/revdebug/how-to-guides/how-to-add-an-ssl-certificate.md) to your RevDeBug.

### Start RevDeBug Server

Then start RevDeBug server by executing:

{% tabs %}
{% tab title="Default" %}

```bash
sudo docker compose -p revdebug up -d
```

{% endtab %}

{% tab title="Standalone" %}

```bash
sudo docker-compose -p revdebug up -d
```

{% endtab %}
{% endtabs %}

Remember to log in to your RevDeBug instance, you also need to add users to your [keyclaoak panel](#keycloak-panel-configuration).

### **Troubleshooting**

* After starting server please give 1-2 minutes for the keycloack authentication bridge to start before attempting to log in.
* If the .env configuration file was misconfigured, it may be necessary to remove the keycloak configuration file located in `REVDEBUG_VOLUME_PATH`/keycloak (`REVDEBUG_VOLUME_PATH` defaults to /var/revdebug/**,** so the path by default should be: /var/revdebug/keycloak/). Removing this directory and restarting the server involves the loss of the previous keyclack configuration along with the created user account&#x73;**.**

### Docker-compose commands quick reference:

{% tabs %}
{% tab title="Default" %}

<table><thead><tr><th width="479">Command</th><th>Effect</th></tr></thead><tbody><tr><td><strong><code>docker compose -p revdebug up -d</code></strong></td><td>Starting RevDeBug Server</td></tr><tr><td><strong><code>docker compose -p revdebug down</code></strong></td><td>Stopping RevDeBug Server</td></tr><tr><td><strong><code>docker compose -p revdebug restart</code></strong></td><td>Restarting RevDeBug Server</td></tr><tr><td><strong><code>docker compose -p revdebug logs --tail=100</code></strong></td><td>Displaying logs of RevDeBug server and all of its services<br>(limited to the last 100 lines)</td></tr></tbody></table>
{% endtab %}

{% tab title="Standalone" %}

<table><thead><tr><th width="494">Command</th><th>Effect</th></tr></thead><tbody><tr><td><strong><code>docker-compose -p revdebug up -d</code></strong></td><td>Starting RevDeBug Server</td></tr><tr><td><strong><code>docker-compose -p revdebug down</code></strong></td><td>Stopping RevDeBug Server</td></tr><tr><td><strong><code>docker-compose -p revdebug restart</code></strong></td><td>Restarting RevDeBug Server</td></tr><tr><td><strong><code>docker-compose -p revdebug logs --tail=100</code></strong></td><td>Displaying logs of RevDeBug server and all of its services<br>(limited to the last 100 lines)</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

(usually, docker-compose commands are executed using `sudo` command like in the example above)

RevDeBug comes pre-configured. If you need to customize it to your needs, [here ](/revdebug/installing-revdebug-server/server-settings-overview.md)you will find a list of available options for configuring your RevDeBug instance.

## **Keycloak panel configuration**

After starting the server please give 1-2 minutes for the keycloack authentication bridge to start before attempting to log in.

To log in to the RevDeBug instance with the keycloak you need to create a user account in the configuration panel. To do so, enter the *servername.your.domain.com/auth*, and then go to the administration console. Here, login using the data specified in `KEYCLOAK_USER` and `KEYCLOAK_PASSWORD` variables in the .env configuration file ([see Settings overview](#settings-overview-set-up-in-.env-file)).

![keycloak configuration panel](/files/jPXFXNDgTRUDSq3k6Rgw)

* Logging will lead you to the Keycloak configuration with RdbRealm selected. To add a user, go to the Users tab, then click the Add user button (right side of the screen).&#x20;
* First, fill in the username field and press the “Save” button.
* Next navigate to the Credentials tab, where the user password should be specified. If you leave the "Temporary" option checked, the user will have to change the password after the first login.
* The last step assigning a role to the new user. Go to the Role Mapping tab, choose roles from Available Roles then click on “add selected”. Available roles:
  * `Disabled`-  Blocked user
  * `User`- Permission to view the dashboards, performance metrics, alarms, and traces.
  * `Developer`-  Permissions are the same as User plus the ability to view the recordings.
  * `Admin/Sysop` - Permissions the same as Developer plus the ability to manage RevDeBug configuration.

## **Enabling license for RevDeBug server**

The last configuration step in the installation process is uploading the license file. To obtain the license file, please contact us at:

<mark style="color:blue;">**<sales@revdebug.com>**</mark>

After obtaining the license and completing the previous steps, go to h*ttp\://servername.your.domain.com* you should see the license loading screen

![](/files/PXFEHGTcqjqxnpTIrhJT)

Upload your license using the “Choose File” button or drag and drop it to the area marked with the dashed line.

Another option is to manually add a license file on the server. To do this rename the license file to “license.dat” and then transfer it to the server and place it inside the directory specified by REVDEBUG\_VOLUME\_PATH variable in the .env file (default is /var/revdebug/server/repo/). Then restart RevDeBug containers.

## **Activate new license file**

You can check your license by navigating to the License page. Switch to **`Flight Recorder`** tab and expand the settings list (top right corner  with gears icon)

![](/files/NnX4DnPkQl36oXg4uUa0)

&#x20;On the license page, you can:

* Read the name of the organization the license is issued to
* Check license validity dates
* Upload a new license (the old license file is replaced with the new one).

Expiring license notifications. There are two types of notifications displayed at the top of the RevDeBug application web interface:

* **`Warning`** - it’s active from the 10th day to the 7th day before the end of the license validity date
* **`Red Alert` -** it’s active from the 7th day to the last day of license validity

## Instrumenting and monitoring applications

Congratulations! You have your own RevDeBug instance running. To start monitoring and error recording your applications please refer to the dedicated technology stack guides:

* [C#](/revdebug/supported-langauges/c.md)
* [JAVA](/revdebug/supported-langauges/java.md)
* [JavaScript](/revdebug/supported-langauges/javascript.md)
* [Python](/revdebug/supported-langauges/python.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://revdebug.gitbook.io/revdebug/installing-revdebug-server.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.