On-Premise Setup of Codelantis with GitLab

To set up Codelantis on your own server ("on-premise"), you'll need to do the following:

1. Create a GitLab OAuth application for Codelantis

To allow users to sign in with GitLab, Codelantis needs an OAuth application to be registered in your Gitlab instance. Without this application, every Codelantis user would have to create and manage a GitLab access token on their own.

To create an OAuth application in Gitlab, you'll need to do the following:

1. Sign into GitLab with the user that will manage the OAuth application. Note that other GitLab users will not gain additional permissions through this application.
2. Click on your user avatar and go to Preferences --> Applications
3. Add a new application with the following data:
   • Name: Codelantis
   • Redirect URI: <YOUR_CODELANTIS_SERVER_URL>/auth/callback/gitlab (with <YOUR_CODELANTIS_SERVER_URL> being the URL of your Codelantis instance)
   • Confidential: ✔️
   • Scopes: api and read_user ^[1]
4. After saving the application, please copy the application id (we'll call this <YOUR_GITLAB_APP_ID>) and the secret (<YOUR_GITLAB_APP_SECRET>).

2. Install Codelantis on your server using Docker

You can install Codelantis on your server using Docker. In this guide, we'll use docker-compose to keep things easy to read.

The docker image of Codelantis is hosted on Docker Hub. If you want to connect to private GitLab repositories, a Codelantis license is required.

Here is a sample docker-compose.yml file, along with with explanations of the parameters.

docker-compose.yml

version: '3'

services:
  codelantis:
    image: 'cdlnts/codelantis:latest'
    container_name: codelantis
    environment:
      # The full, user-facing URL of your Codelantis instance.
      # Has to be the same url as specified in the GitLab OAuth app
      # Example: 'https://codelantis.example.com'
      - CODELANTIS_ORIGIN=<YOUR_CODELANTIS_SERVER_URL>

      # The GitLab OAuth app id and secret from step 1
      - GITLAB_ID=<YOUR_GITLAB_APP_ID>
      - GITLAB_SECRET=<YOUR_GITLAB_APP_SECRET>

      # The URL of your GitLab instance (default: 'https://gitlab.com')
      - GITLAB_BASE_URL=<YOUR_GITLAB_URL>

      # A generated secret (random string) consumed internally by Codelantis.
      # Should not be changed after its initial value has been set
      - AUTH_SECRET=<YOUR_AUTH_SECRET>

      # The SQLite database file used by Codelantis.
      # For a MySQL database, use mysql: as prefix (see example below).
      - DATABASE_URL=file:/var/db/app.db

      # MySQL example: The database URL connecting to a MySQL database outside of the Codelantis container,
      # following the schema described in https://www.prisma.io/docs/reference/database-reference/connection-urls
      # More URL arguments (e.g. for sockets) can be added as specified here: https://www.prisma.io/docs/concepts/database-connectors/mysql
      # - DATABASE_URL=mysql://<YOUR_DB_USER>:<YOUR_DB_PASSWORD>@<DB_URL>:<DB_PORT>/<DB_NAME>

      # Data from your Codelantis license
      - CODELANTIS_LICENSE_KEY=<YOUR_LICENSE_KEY>
      - CODELANTIS_LICENSEE=<YOUR_LICENSEE>
      - CODELANTIS_MAX_USERS=<YOUR_LICENSE_USER_COUNT>
      - CODELANTIS_LICENSE_VALID_UNTIL=<YOUR_LICENSE_VALID_UNTIL>

    # A user that may read from/write to the database directory on your host system
    # (only relevant if SQLite is configured as database above)
    user: <YOUR_HOST_USER>:nodeuser
    volumes:
      - /var/run/docker.sock:/docker.sock

      # The path to the database directory on your host system.
      # While this is only needed for SQLite, it won't cause errors when other databases are configured.
      # You can change the left part to another folder on your host system (but you don't have to)
      - ./db:/var/db
    restart: always
    ports:
      # The port on the host machine where Codelantis should be reachable.
      - '<CODELANTIS_HOST_PORT>:3000'

With all of the parameters set, you should now be able to run

docker compose up -d

and have a running Codelantis instance on the port you specified.

Verifying the setup works

To ensure everything works as intended, the following steps can be taken:

1. Open the URL of your Codelantis instance ($CODELANTIS_ORIGIN above) in your browser
2. Paste the URL to an arbitrary GitLab merge request of your GitLab instance or gitlab.com, respectively.
3. You should be prompted to authenticate your current user with your Gitlab instance
4. After the authentication with GitLab, your merge request should be shown in Codelantis