Important

These are the guides for version v0.2.0, and may not work with the latest code in the main or dev branch.

Refer to this page's commit history for previous versions.

Thank you for your interest in Lanbassador! At this time, the only available and recommended installation method is using Docker Compose.

🐋 Deployment with Docker Compose (recommended)

Before starting, you'll need a few requirements first.

🗒️ Requirements

• A Linux box (this should work with other *NIXes, but this was only tested under Linux)
• An active internet connection (during first setup)
• Docker daemon
• Docker Compose

If you are using Debian 12 and later, you can use the following commands to install the dependencies:

# apt-get install docker.io docker-compose

Note

This guide assumes you are pulling the official images.

If you are building the Lanbassador images from source, then you will also need Git installed to clone the repository. Do not download a source archive!

💾 Obtaining the sources

You must clone the Lanbassador repository before continuing. You can either download a source archive from the repository and extract it to a directory (e.g., lanbassador/), or clone it if you have Git installed:

git clone 'https://git.luca0n.com/luca0N/lanbassador'
cd lanbassador

There are two configuration files that you will need before starting Lanbassador. These two files are already in the repository you have cloned, so you can just copy them to the root of the cloned directory:

# Copy the web app client configuration file
cp client/lanbassador-config.json lanbassador-client.json

# Copy the server configuration file
cp server/server.cfg .

You are encouraged to read these files and adjust their settings to your liking, but keep in mind that there are some preferences that you must adjust before starting to use Lanbassador. Keep on reading the guide for further information.

✏️ Setting the Lanbassador initial preferences

There are several preferences that you can change in Lanbassador (especially in the server configuration file), but for now we'll focus on changing the bare minimum so that it's usable. You can explore the configuration files yourself and tune it as you wish!

Now, it's time to specify which NIC Lanbassador should listen on. If you are not sure which one you should use, run the ip link command. Ethernet NICs are usually named ens followed by a number, and Wi-Fi NICs usually start with wlan and a number. In docker-compose.yaml, go to the server service, and change the LANBASSADOR_INTERFACE value to the NIC name that you would like to use, like so:

services:
  client:
    # ...

  server:
    # ...

    environment:
      LANBASSADOR_INTERFACE: ens3

    # ...

Important

Please note that the server service network must not be changed from host, otherwise, unknown hosts in the network are not going to be visible to the container.

You should also modify the web app client configuration file so that it correctly points to your server IP address. Because the server container runs with the host network mode, it is bound to the host IP address. Open lanbassador-client.json with your favorite text editor, and modify the host string in the server object:

{
    "server": {
        "useTls": false,
        "host": "nebula.luca0n.com",
        "port": 8080
    }
}

Note

TLS is not natively supported in the Lanbassador server. If you wish to use TLS, then you must use a reverse proxy at this time and specify its host and port in the web app client configuration file.

In the example above, host was modified to be "nebula.luca0n.com". Users visiting the web app client will connect to this host at the specified port (8080) with TLS disabled. Be sure that any applicable firewalls are not in the way of clients and the server host.

Once done, start the Docker Compose service. Note that docker-compose has changed to docker compose in newer versions of Docker Compose:

# docker-compose up

The Lanbassador interface should be available from your browser based on the docker-compose.yaml file. If you are using the default values, you should be able to access the interface on http://localhost:8085/. Well done!