Skip to main content
Version: v0.17

Install via Docker Compose

Prerequisites​

Launch DevLake​

  1. Download docker-compose.yml and env.example from the latest release into a folder.
  2. Rename env.example to .env. For Mac/Linux users, please run mv env.example .env in the terminal. This file contains the environment variables that the Devlake server will use. Additional ones can be found in the compose file(s).
  3. Run docker-compose up -d if the version of Docker Desktop is too low to use docker compose up -d.

Collect data and view dashboards​

  1. Visit "config-ui" at http://localhost:4000 in your browser to configure DevLake and collect data.
    • Please follow the tutorial
    • "devlake" container takes a while to fully boot up. If "config-ui" complains about API being unreachable, please wait a few seconds and refresh the page.
  2. To view dashboards, click View Dashboards button in the top left corner, or visit localhost:3002 (username: "admin", password: "admin").
    • We use Grafana to visualize the DevOps data and build dashboards.
    • For how to customize and provision dashboards, please see our Grafana doc.

Upgrade to a newer version​

Please note: Back up your Grafana dashboards before upgrading if you have modified/customized any dashboards. You can re-import these dashboards to Grafana after the upgrade.

  1. Run docker-compose down to stop services;
  2. Open file "docker-compose.yml". Change the image tags of "grafana", "devlake" and "config-ui" to the new version, and save;
  3. Run docker-compose up -d to start DevLake services.

Please check the upgrade doc for more information.

FAQ​

Can I use a managed cloud database service instead of running database in Docker?​

Yes, please follow the steps below:

  1. Comment out the 'mysql' part in docker-compose.yml:
mysql:
  image: mysql:8
  volumes:
    - mysql-storage:/var/lib/mysql
  restart: always
  ports:
    - "127.0.0.1:3306:3306"
  environment:
    MYSQL_ROOT_PASSWORD: admin
    MYSQL_DATABASE: lake
    MYSQL_USER: merico
    MYSQL_PASSWORD: merico
  command: --character-set-server=utf8mb4
    --collation-server=utf8mb4_bin
  1. Comment out the 'mysql' volume in docker-compose.yml:
volumes:
  mysql-storage:
  1. Comment out the 'depends_on mysql' part in docker-compose.yml:
depends_on:
  - mysql
  1. Provide your managed cloud database connection info in the 'grafana' section in docker-compose.yml:
  • MYSQL_URL: This parameter specifies the URL of your database instance. For example, if your database is hosted on a server with IP address 123.45.67.89 and port number 3306, the URL would be "123.45.67.89:3306".
  • MYSQL_DATABASE: This parameter specifies the name of your database. For example, if your database is named "mydatabase", you would set this parameter to "mydatabase".
  • MYSQL_USER: This parameter specifies the username that you will use to connect to your database. For example, if your username is "myuser", you would set this parameter to "myuser".
  • MYSQL_PASSWORD: This parameter specifies the password that you will use to connect to your database. For example, if your password is "mypassword", you would set this parameter to "mypassword".
MYSQL_URL: 123.45.67.89:3306
MYSQL_DATABASE: mydatabase
MYSQL_USER: myuser
MYSQL_PASSWORD: mypassword
  1. Set DB_URL to your own DB_URL in .env:
DB_URL="mysql://YOUR_USER:YOUR_PASSWORD@YOUR_IP:YOUR_PORT/lake?charset=utf8mb4&parseTime=True"
# Don't forget to create db named `lake` in your own db, and set character-set-server=utf8mb4, collation-server=utf8mb4_bin as below
#      character-set-server=utf8mb4
#      collation-server=utf8mb4_bin
  1. Final step: docker compose up -d

Can I use an external Grafana instead of running Grafana in Docker?​

Yes, please follow the steps below:

  1. Comment out the 'grafana' part:
grafana:
  image: mericodev/devlake-dashboard:latest
  build:
    context: grafana/
  ports:
    - "3002:3000"
  volumes:
    - grafana-storage:/var/lib/grafana
  environment:
    GF_SERVER_ROOT_URL: "http://localhost:4000/grafana"
    GF_USERS_DEFAULT_THEME: "light"
    MYSQL_URL: mysql:3306
    MYSQL_DATABASE: lake
    MYSQL_USER: merico
    MYSQL_PASSWORD: merico
  restart: always
  depends_on:
    - mysql
  1. Comment out grafana volume:
volumes:
  grafana-storage:
  1. Set up the config-ui container to adopt the external Grafana in the docker-compose.yml
config-ui:
  ...
  environment:
    USE_EXTERNAL_GRAFANA: "true"
    GRAFANA_ENDPOINT: "http://grafana.example.com"
  ...

  1. Please connect your Grafana to DevLake's database by following https://grafana.com/docs/grafana/latest/administration/data-source-management/

  2. If you want to import dashboards, please check https://grafana.com/docs/grafana/latest/dashboards/export-import/.

  1. Final step: docker compose up -d

Troubleshooting​

If you run into any problem, please check the Troubleshooting or create an issue