You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: consolidate setup guides and fix outdated instructions
Point new developers to a single Docker live-reload path, remove duplicated
env and compose instructions, and correct stale commands, ports, and links.
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+9-6Lines changed: 9 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,15 +4,18 @@ KernelCI Dashboard is an open-source project and contributions of all kinds are
4
4
5
5
## Before you start
6
6
7
-
- Read the README for an overview of the monorepo.
8
-
- We recommend following the [Onboarding guide](./docs/Onboarding.md) to set up your environment and learn the project workflow. **Start here** if this is your first setup.
9
-
- New to the project? Pick an issue labeled ["good first issue"](https://github.com/kernelci/dashboard/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
10
-
- There are a couple of extensions that may help you with linting and formatting your code. Consider installing [ESLint](https://eslint.org/) and [Prettier](https://prettier.io/) for your preferred code editor.
11
-
- For Python development, this repository uses [Ruff](https://docs.astral.sh/ruff/) for linting and formatting, and [pre-commit](https://pre-commit.com/) for Git hooks.
7
+
1. Read the [README](./README.md) for a project overview.
8
+
2. Set up locally:
9
+
-**Docker with live reload:**[docs/dev-environment.md](./docs/dev-environment.md) — or run `make setup` then `make dev`
-**Manual backend + frontend on the host:**[backend/README.md](./backend/README.md) and [dashboard/README.md](./dashboard/README.md)
12
+
3. New to the project? Pick an issue labeled ["good first issue"](https://github.com/kernelci/dashboard/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
13
+
4. For Python development, this repository uses [Ruff](https://docs.astral.sh/ruff/) and [pre-commit](https://pre-commit.com/). For the frontend, consider [ESLint](https://eslint.org/) and [Prettier](https://prettier.io/) in your editor.
12
14
13
15
## Useful links
14
16
15
17
- README: [./README.md](./README.md)
18
+
- Dev environment: [./docs/dev-environment.md](./docs/dev-environment.md)
Copy file name to clipboardExpand all lines: DEPLOYMENT.md
+14-55Lines changed: 14 additions & 55 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,12 +1,15 @@
1
1
# KernelCI Dashboard — Deployment Guide
2
2
3
-
This guide covers three deployment scenarios: [development](#1-development), [production](#2-production), and [staging](#3-staging).
3
+
This guide covers three deployment scenarios: [containerized staging-like local run](#1-containerized-staging-like-local-run), [production](#2-production), and [staging](#3-staging).
4
+
5
+
For contributor live reload, see [docs/dev-environment.md](docs/dev-environment.md) instead.
4
6
5
7
## Quick Reference
6
8
7
9
| Scenario | Compose File | Database | Profiles |
8
10
|----------|-------------|----------|----------|
9
-
| Development |`docker-compose.yml`| Local (always on) |`with_commands` (for ingester) |
11
+
| Contributor live reload |`docker-compose.dev.yml`| Local | — |
12
+
| Staging-like local run |`docker-compose.yml`| Local (`dashboard_db`) |`with_commands` (for ingester) |
10
13
| Production |`docker-compose-next.yml`| External PostgreSQL | none (or `with_commands`) |
@@ -15,7 +18,7 @@ This guide covers three deployment scenarios: [development](#1-development), [pr
15
18
## Table of Contents
16
19
17
20
-[Prerequisites](#prerequisites)
18
-
-[1. Development](#1-development)
21
+
-[1. Containerized staging-like local run](#1-containerized-staging-like-local-run)
19
22
-[2. Production](#2-production)
20
23
-[3. Staging](#3-staging)
21
24
-[Profile Reference](#profile-reference)
@@ -50,24 +53,13 @@ This guide covers three deployment scenarios: [development](#1-development), [pr
50
53
51
54
### Accessing production database
52
55
53
-
If direct access to the production database is required,
54
-
whether for local debugging or validating critical feature development,
55
-
you must request permissions for the SSH connection and database user.
56
+
See [Onboarding Task 0](docs/Onboarding.md#task-0-check-your-ssh-and-database-access) for SSH tunnel and credential setup.
56
57
57
-
1. Connect to the Azure database SSH bridge:
58
-
- Create a new SSH key and add it to your SSH agent.
59
-
- Share the public SSH key to the database maintainer, to be granted access
60
-
to the SSH tunnel.
61
-
- Connect to the database via SSH tunnel with the provided URL.
62
-
2. Request credentials: Obtain a new username and password for the database access.
63
-
3. Connect: Once you have your credentials, connect to the database via `psql`, `pgAdmin`,
64
-
`DBeaver`, or any other PostgreSQL manager.
58
+
## 1. Containerized staging-like local run
65
59
66
-
## 1. Development
60
+
> For contributor live reload (Django + Vite HMR), use [docs/dev-environment.md](docs/dev-environment.md) (`docker-compose.dev.yml`) instead.
67
61
68
-
This is the minimal guide for development using
69
-
the fully containerized (Docker Compose) alternative.
70
-
Images are built locally and use a global `.env` file.
62
+
This section covers a staging-like stack built from source with Gunicorn and a production-style frontend image. Images are built locally and use root `.env`. The proxy defaults to port **9000**.
71
63
72
64
### Setup
73
65
@@ -95,40 +87,9 @@ docker compose up --build -d backend
95
87
docker compose up --build -d
96
88
```
97
89
98
-
### Local Frontend development
99
-
100
-
When implementing frontend features, a fast "hot reload" workflow
101
-
is usually preferred. In these scenarios, it is recommended to
102
-
run a local frontend server on the host machine.
103
-
104
-
For active frontend work, we can run the Vite dev server directly:
105
-
106
-
```bash
107
-
cd dashboard
108
-
pnpm install
109
-
# Copy the example env file and verify VITE_API_BASE_URL
110
-
cp .env.example .env
111
-
pnpm dev
112
-
```
113
-
114
-
The frontend connects to the backend API via the `VITE_API_BASE_URL`
115
-
defined in `dashboard/.env` (defaults to `http://localhost:8000`).
116
-
117
-
### Local Backend development
118
-
To implement backend features with hot reloading,
119
-
you can also start a local Django instance.
120
-
121
-
```bash
122
-
cd backend
123
-
poetry install
124
-
125
-
# Copy the env file and edit the DB_* to match your local database instance.
126
-
# Also set DEBUG=True to allow CORS connections and stack traces.
127
-
poetry run python3 manage.py runserver
128
-
```
90
+
### Host-based development
129
91
130
-
The backend connects to a PostgreSQL instance using the environment variables:
For hot reload on the host machine, see [dashboard/README.md](dashboard/README.md) (frontend) and [backend/README.md](backend/README.md) (backend). Point `VITE_API_BASE_URL` in `dashboard/.env` at your backend (default `http://localhost:8000`).
132
93
133
94
---
134
95
@@ -138,9 +99,7 @@ Unlike the development deployment, our production environment connects to a
138
99
pre-existing external PostgreSQL instance and use pre-built docker images
139
100
stored in the GitHub Container Registry (GHCR).
140
101
141
-
Production images are automatically built via GitHub Workflow,
142
-
to every new commit in the main branch, or when
143
-
the `Publish GHCR Images` workflow is triggered manually.
102
+
Production images are built on every push to main and when [deploy-containers.yaml](.github/workflows/deploy-containers.yaml) is triggered manually (`workflow_dispatch`).
144
103
145
104
The GitHub workflow for production is defined at: [deploy-production](.github/workflows/deploy-production.yaml)
Copy file name to clipboardExpand all lines: README.md
+14-94Lines changed: 14 additions & 94 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -20,104 +20,26 @@ A Python http server built with [Django](https://www.djangoproject.com/) + [DRF]
20
20
21
21
## Quick run
22
22
23
-
If you want to just run the project, you can try out pre-built images with the [docker-compose-next.yml](./docker-compose-next.yml) file. This pulls images from GHCR and runs them locally without needing to rebuild them. You may still need to set up environment variables, so read the docs.
23
+
To run pre-built images without rebuilding, use [docker-compose-next.yml](./docker-compose-next.yml). Copy [`.env.example`](.env.example) to `.env`, set required values, then start the stack. The proxy defaults to port **80**. See [DEPLOYMENT.md](./DEPLOYMENT.md) for details.
24
24
25
-
## Build
25
+
## Local development
26
26
27
-
### Frontend
27
+
Pick the workflow that fits how you want to work:
28
28
29
-
Create a .env file in /dashboard, check and set the variables and their values
30
-
```sh
31
-
cp ./dashboard/.env.example ./dashboard/.env
32
-
```
29
+
| Workflow | Guide |
30
+
|---|---|
31
+
| Docker with live reload (recommended) |[docs/dev-environment.md](docs/dev-environment.md) — `make dev` or `docker compose -f docker-compose.dev.yml up -d`|
32
+
| Manual backend + frontend on the host |[backend/README.md](backend/README.md) and [dashboard/README.md](dashboard/README.md)|
33
+
| Staging-like container run (no live reload) |[DEPLOYMENT.md](./DEPLOYMENT.md) §1 |
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.
35
-
36
-
We use `pnpm` to help with the package management. Install the dependencies with
37
-
```sh
38
-
pnpm install
39
-
```
40
-
41
-
Then start the dev server with
42
-
```sh
43
-
pnpm dev
44
-
```
45
-
46
-
If you want to test the production state of the dashboard, use
We are not using sessions or anything like that right now, so changing the secret key won't be a big deal.
64
-
65
-
Since the production *database* is not open for the public, we use ssh tunneling with a whitelist to access it. This means that the docker setup currently can't access it, but we have a local database that is connected automatically if you don't change the env vars.
66
-
67
-
If you do use docker, you should create a secret file with the database password:
It is also possible to run the backend outside of docker for development purposes. Simply run the ssh tunnel with the instructions sent to you by the database manager, then export the variables seen in [.env.backend.example](/.env.backend.example).
84
-
85
-
> For other optional envs, check the [backend README](backend/README.md).
86
-
87
-
### Common
88
-
89
-
Startup the services:
90
-
```sh
91
-
docker compose up --build -d
92
-
```
93
-
Docker exposes port 80 (that you don't need to enter in the URL) instead of 5173 and 8000 that is used when running the dashboard project outside of docker.
94
-
So you can hit the frontend with `http://localhost` and the backend with `http://localhost/api` when running locally.
95
-
96
-
Make sure that docker has the right permissions and has access to the environment variables. One way to do that is to set up a docker permission group.
97
-
98
-
If you are running the commands for exporting the environment variables and running docker separately, you can run docker with admin privileges and allowing environment variables with:
99
-
```sh
100
-
sudo -E docker compose up --build -d
101
-
```
102
-
Or you can also run the env exports and docker compose within the root user by running `sudo su`.
103
-
104
-
> Tip: you can create a quick script to set all the necessary envs and start the services. This will also allow docker to see the environment variables correctly. Example:
> [Note] If you are going to run using only the local database, the DB_NAME should be `dashboard` and the `DB_USER` and `DB_PASSWORD` should be `admin` (for now). This simply follows what is going to be setup by the `dashboard_db` service on docker compose.
36
+
**Env files:** Docker Compose reads root `.env` plus `dashboard/.env`. For manual backend runs, export variables from [`.env.backend.example`](.env.backend.example) (Django does not load that file automatically).
116
37
38
+
**Ports:**`docker-compose.dev.yml` and `docker-compose.yml` expose the app at `http://localhost:9000` by default. Running services on the host uses `5173` (frontend) and `8000` (backend). `docker-compose-next.yml` defaults to port **80**.
117
39
118
40
## Deploying to production
119
41
120
-
See [DEPLOYMENT.md](./DEPLOYMENT.md) for full deployment instructions covering development, staging, and production scenarios.
42
+
See [DEPLOYMENT.md](./DEPLOYMENT.md) for staging, production, and deployment scenarios.
121
43
122
44
To deploy to prod you need to push a tag in the `release/YYYYMMDD.N` format
123
45
like: `release/20240910.0`
@@ -149,8 +71,6 @@ If you want to verify container/deployment environment settings before running s
149
71
-[docs/verify_env.md](docs/verify_env.md) for detailed examples, including test email sending to a specific destination
150
72
- Destination is required with `--send-test-email` and `--to-email`.
151
73
152
-
## Contributing
153
-
154
-
Check out our [CONTRIBUTING.md](/CONTRIBUTING.md), and there is an [onboarding guide](docs/Onboarding.md) to help get acquainted with the project. Contributions are welcome!
74
+
## Contributing
155
75
156
-
For a local development environment with live reload (backend + frontend), see [docs/dev-environment.md](docs/dev-environment.md). That Docker-based workflow uses a root `.env` file plus `dashboard/.env`; the backend-specific manual setup above still uses `.env.backend`. Use the env files required by the workflow you choose.
76
+
Check out [CONTRIBUTING.md](./CONTRIBUTING.md) and the [onboarding guide](docs/Onboarding.md). Contributions are welcome!
0 commit comments