[WIP] docs: consolidate setup guides and fix outdated instructions by mentonin · Pull Request #1944 · kernelci/dashboard

mentonin · 2026-06-19T16:32:23Z

Description

Documentation-only PR that consolidates overlapping setup instructions and fixes stale
references for new developers. No new docs added — existing content was trimmed,
corrected, and cross-linked.

Establish one recommended Docker path: docs/dev-environment.md
Replace duplicated setup blocks in README, Onboarding, and DEPLOYMENT with pointers to the canonical guides
Clarify env file usage: root .env + dashboard/.env for Docker; .env.backend.example for manual backend exports only
Fix outdated commands and details: frontend pnpm paths, proxy ports (9000 vs 80), .env.development, removed Google Cloud reference, broken monitoring link, missing copy_db_data.sh

Point new developers to a single Docker live-reload path, remove duplicated env and compose instructions, and correct stale commands, ports, and links.

MarceloRobert

Some really needed changes, it's good to make things more concise. I added some comments

MarceloRobert · 2026-06-22T10:54:31Z

 ## Cron jobs

-We have support for cron jobs using django-crontab. To set up cron jobs, edit the `CRONJOBS` variable in /backend/kernelCI/settings.py
+We have support for cron jobs using django-crontab. To set up cron jobs, edit the `CRONJOBS` variable in `kernelCI/settings.py`.


nit: since you are changing this you could also add a hyperlink to the file

MarceloRobert · 2026-06-22T11:10:33Z

 ### Databases

-For the main database, the backend uses a series of `DB_` environment variables that have to be set such as:
+Export variables from [`.env.backend.example`](../.env.backend.example) (Django does not load that file automatically). Example for the **production database via SSH tunnel**:


I actually hadn't noticed that in a local backend run it won't use the .env.backend but it does make sense. However, I also found that you can set VSCode to inject values from .env files to the terminal (on setting python.terminal.useEnvFile) so you don't have to export the variables all the time, maybe it's worth mentioning it, what do you think?

MarceloRobert · 2026-06-22T11:13:36Z


-> [!IMPORTANT]
-> The current docker compose has settings meant for the staging deployment; for local development you'll need to open the `dashboard_db` service's port (set `5434:5432` so the external port doesn't conflict with the backend) and set `STAGING_EXTERNAL_HTTP_PORT` as `80` in `.env`.
+Follow [dev-environment.md](dev-environment.md) (`make dev` or `docker compose -f docker-compose.dev.yml up -d`). Stop any local backend, frontend, SSH tunnel, and Redis first — if Redis was installed via snap, run `sudo snap stop redis`.


I'd keep the IMPORTANT tag, and also explain briefly why we use a specific "dev docker" (because the staging ones don't export the db port and it has other security measures that don't apply/hinder to local development)

MarceloRobert · 2026-06-22T11:15:00Z

-```bash
-docker compose up --build -d
-```
-
-After starting the services, you can check if your Docker containers are running with:
-
-```bash
-docker ps
-```
-
-If any container fails or exits unexpectedly, you can inspect the logs with:
-
-```bash
-docker logs <container_id>
-```


I think these commands might be useful for a developer; what's the reason to remove them?

MarceloRobert · 2026-06-22T11:17:13Z

 ## Notes

- The command uses settings from `kernelCI/settings.py` plus the environment values in `.env.backend`.
+- The command uses settings from `kernelCI/settings.py` plus environment values from root `.env` when run via Docker Compose. For manual backend runs, export variables from [`.env.backend.example`](../.env.backend.example).


wait, if there's no docker compose using .env.backend, why do we have it?

alanpeixinho · 2026-06-22T20:50:50Z

 export DB_OPTIONS_CONNECT_TIMEOUT=16
 ```

+For the **local Docker database**, use `DB_NAME=dashboard`, `DB_USER=admin`, and the password from root `.env`.


wont all variables db_name, db_user and db_password come from .env?
I think we could mention they are defined there, and the default values are dashboard/admin

alanpeixinho · 2026-06-22T21:07:44Z

 ## Running end-to-end (e2e) tests

-The project includes Playwright-based end-to-end tests. To run the tests, first set the test environment URL in your .env file:
+Set `PLAYWRIGHT_TEST_BASE_URL` in `.env` (defaults to staging). Install browsers once with `pnpm exec playwright install`, then:


I know this is not included here, but since we are already reviewing docs ...
Why do we set VITE_API_BASE_URL environment, but add PLAYWRIGHT_TEST_BASE_URL on .env?
Cant we use the same approach for both?

alanpeixinho · 2026-06-22T21:09:52Z

-# Run e2e tests with UI mode for debugging
-pnpm run e2e-ui
-```
+Available base URLs: staging (`https://staging.dashboard.kernelci.org`), production (`https://dashboard.kernelci.org`), local Vite (`http://localhost:5173`), local proxy (`http://localhost:9000`).


Dont know if it is a good idea to add production as one of the choices for e2e tests.
But if we want to present this choice, we could add a warning to prefer staging or local instances.

alanpeixinho · 2026-06-22T21:14:23Z

 **Step 2: Execute migrations**
 ```bash
-docker compose -f docker-compose.test.yml run --rm test_backend python manage.py migrate
+docker compose -f docker-compose.test.yml run --rm test_backend poetry run python manage.py migrate


on the Makefile we are not using the poetry cli, should we change there?

alanpeixinho · 2026-06-22T21:16:46Z

-echo "PROMETHEUS_METRICS_PORT=8001" >> .env.backend
-echo "PROMETHEUS_MULTIPROC_DIR=/tmp/prometheus_multiproc_dir" >> .env.backend
+# Add monitoring configuration to root .env
+echo "PROMETHEUS_METRICS_ENABLED=true" >> .env


is .env.backend being used anywhere? if not, we might as well remove it

alanpeixinho · 2026-06-22T21:28:56Z

+| Staging-like container run (no live reload) | [DEPLOYMENT.md](./DEPLOYMENT.md) §1 |
+| Guided first-time setup | [docs/Onboarding.md](docs/Onboarding.md) |

-With docker, you can start just the frontend with `docker compose up --build proxy`. It is also possible to run the dashboard outside of it for development purposes.


shouldnt we keep a guide on how to run the project without docker? even if we recommend the docker path?

MarceloRobert · 2026-06-24T12:08:08Z

One thing that I remembered now - but please don't make it a blocker - is that when I was setting up the project I ran into a problem with Python 3.14, so I had to install Python 3.13 to use it in poetry and then it worked normally; this may be worth a quick mention in the docs. The problems occurred with the libraries pydantic-core and rpds-py.

Since it's a dev setup problem and I was able to figure it out quickly I didn't bother making an issue, but I can create it if you guys prefer it too.

docs: consolidate setup guides and fix outdated instructions

2fac254

Point new developers to a single Docker live-reload path, remove duplicated env and compose instructions, and correct stale commands, ports, and links.

mentonin force-pushed the georg/doc-overhaul branch from 2603df4 to 2fac254 Compare June 19, 2026 16:32

MarceloRobert reviewed Jun 22, 2026

View reviewed changes

alanpeixinho reviewed Jun 22, 2026

View reviewed changes

Uh oh!

Conversation

mentonin commented Jun 19, 2026

Description

Uh oh!

MarceloRobert left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MarceloRobert commented Jun 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants