Skip to content

Commit abc5638

Browse files
henrikmagnihenrikmagni
authored
Merge pull request #71 from OS2borgerPC/mere_drift_dokumentation
udvid dokumentation omkring drift
2 parents 64f4885 + 1332203 commit abc5638

File tree

1 file changed

+105
-58
lines changed

1 file changed

+105
-58
lines changed

‎drift.md

Lines changed: 105 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -1,110 +1,157 @@
11
# Installation og Drift
22

3-
**OS2BorgerPC admin-site** bygges som et Docker-image. En [bygge-pipeline på GitHub](https://github.com/OS2borgerPC/os2borgerpc-admin-site/actions/workflows/docker-image.yml) bygger og publicerer Docker-image'et til [GitHub Packages](https://github.com/orgs/OS2borgerPC/packages?repo_name=os2borgerpc-admin-site). Her kan du finde image-tags og URL.
3+
## Introduktion
4+
**OS2BorgerPC admin-site** er designet som et Docker-image. Bygning og publicering håndteres af en [GitHub-pipeline](https://github.com/OS2borgerPC/os2borgerpc-admin-site/actions/workflows/docker-image.yml), som uploader Docker-image'et til [GitHub Packages](https://github.com/orgs/OS2borgerPC/packages?repo_name=os2borgerpc-admin-site). Her kan du finde image-tags og URLs.
45

5-
Konfigurationen af admin-site sker via miljøvariabler, som er beskrevet nedenfor. Derudover beskrives også øvrige driftskrav.
6+
Konfiguration sker via miljøvariabler (beskrevet nedenfor) og omfatter desuden specifikationer for driftskrav. En `compose.yaml`-fil leveres som reference til udvikling og konfiguration.
67

7-
En `compose.yaml`-fil er inkluderet til udviklingsbrug og kan bruges som reference for fuld konfiguration. Bemærk, at denne ikke er opdateret til de nye cron job-endpoints, men bruger i stedet et separat image til at udføre dem. Dette fungerer til udvikling, men anbefales ikke til produktion.
8+
**Bemærk:** `compose.yaml` er ikke opdateret til at understøtte de nye cron job-endpoints. Til produktion anbefales brug af de nye cron job endpoints.
89

910
---
1011

11-
## Bootstrapping
12+
## Oversigt over Miljøvariabler
13+
14+
| Variabel | Forklaring | Standardværdi | Påkrævet |
15+
|------------------------------|----------------------------------------------------------------------------|-----------------|----------|
16+
| `ADMIN_USERNAME` | Brugernavn for admin-bruger | Ingen | Ja |
17+
| `ADMIN_PASSWORD` | Adgangskode for admin-bruger | Ingen | Ja |
18+
| `ADMIN_EMAIL` | Email for admin-bruger | Ingen | Ja |
19+
| `DB_HOST` | Databasevært | Ingen | Ja |
20+
| `DB_PORT` | Databaseport | Ingen | Ja |
21+
| `DB_USER` | Brugernavn til databasen | Ingen | Ja |
22+
| `DB_PASSWORD` | Adgangskode til databasen | Ingen | Ja |
23+
| `DB_NAME` | Navn på databasen | Ingen | Ja |
24+
| `CORE_SCRIPT_VERSION_TAG` | Version af de globale scripts | Ingen | Ja |
25+
| `CORE_SCRIPT_COMMIT_HASH` | Matchende commit-hash for scripts | Ingen | Ja |
26+
| `HTTPS_GUARANTEED` | Aktiverer behandling af HTTP som HTTPS bag proxy | false | Nej |
27+
| `PC_IMAGE_RELEASES_URL` | URL til download af BorgerPC ISO images | Ingen | Nej |
28+
| `KIOSK_IMAGE_RELEASES_URL` | URL til download af Kiosk ISO images | Ingen | Nej |
29+
30+
---
31+
32+
## Drift Anbefalinger
33+
34+
For at understøtte leverandører og kommuner i at sætte OS2BorgerPC admin-site i drift samt håndtere opgraderinger anbefales følgende fremgangsmåde:
35+
36+
### Drift Opsætning
37+
1. **Undgå brug af `docker-compose` i produktion:**
38+
- `docker-compose` er velegnet til udvikling, men anbefales ikke til produktion.
39+
- Brug en orkestreringsløsning som Kubernetes eller Docker Swarm til at håndtere containere.
40+
41+
2. **Ønskes brug af docker-compose alligevel eller sammen med Docker Swarm:**
42+
- Lav ny docker-compose fil med udgangspunkt i `compose.yaml`
43+
- Fjern unødvendige services som `frontend` og tilpas `cron-service` som beskrevet nedenfor.
44+
- Konfigurer admin-site til at pege på et specifikt Docker-image-tag, f.eks.:
45+
```yaml
46+
image: ghcr.io/os2borgerpc/os2borgerpc-admin-site:<specific-tag>
47+
```
48+
- Indstil miljøvariabler i henhold til dokumentationen.
49+
50+
3. **Volumenhåndtering:**
51+
- Sørg for at mount persistente volumes til `/media` for at sikre, at scripts og andre uploads bevares mellem genstarter.
52+
- Eksempel:
53+
```yaml
54+
volumes:
55+
- admin-media:/media
56+
```
57+
58+
4. **Sikkerhed:**
59+
- Angiv en stærk `SECRET_KEY` i miljøvariablerne.
60+
- Begræns `ALLOWED_HOSTS` til de domæner, der skal have adgang til admin-site.
61+
62+
### Opgradering af Admin-Site
63+
1. **Forberedelse:**
64+
- Gennemgå release-notes for den nye version.
65+
- Test opgraderingen i et udviklings- eller staging-miljø.
66+
67+
2. **Opdatering:**
68+
- Opdater Docker-image-tagget til den ønskede version i din orkestreringsopsætning.
69+
- Genstart admin-site-containere for at anvende ændringerne.
70+
71+
3. **Validering:**
72+
- Bekræft, at opgraderingen er succesfuld ved at teste kernefunktionalitet.
73+
- Tjek logfiler for fejl eller advarsler.
74+
75+
### Fejlfinding
76+
- Hvis der opstår problemer under opgradering, kan du rulle tilbage til det tidligere Docker-image-tag.
77+
- Kontroller logfiler i admin-site-containere for detaljerede fejlmeddelelser.
78+
79+
---
1280

13-
For at komme i gang med admin-site og få adgang til Djangos administrationsside (`<base URL>/admin`), skal der oprettes en admin-bruger. Da der som standard ikke er nogen admin-bruger, skal denne oprettes ved første opstart med følgende miljøvariabler:
81+
## Bootstrapping
82+
For at initialisere admin-site og få adgang til Djangos administrationsside (`<base URL>/admin`), skal en admin-bruger oprettes med følgende miljøvariabler:
1483

1584
- `ADMIN_USERNAME`
1685
- `ADMIN_PASSWORD`
1786
- `ADMIN_EMAIL`
1887

19-
*Bemærk:* `ADMIN_EMAIL` er en del af Djangos indbyggede brugerhåndtering.
20-
21-
Den oprettede admin-bruger kan også logge ind som almindelig bruger og administrere sites/klienter.
88+
**Bemærk:** `ADMIN_EMAIL` anvendes af Djangos indbyggede brugerhåndtering. Den oprettede admin-bruger kan også administrere sites og klienter.
2289

2390
---
2491

2592
## Database
26-
27-
Følgende miljøvariabler bruges til at konfigurere databaseforbindelsen:
93+
Konfiguration af databaseforbindelsen sker via følgende miljøvariabler:
2894

2995
- `DB_HOST`
3096
- `DB_PORT`
3197
- `DB_USER`
3298
- `DB_PASSWORD`
3399
- `DB_NAME`
34100

35-
Se `compose.yaml` for eksempler på opsætning.
101+
Se `compose.yaml` for eksempler.
36102

37103
---
38104

39105
## Scripts
40-
41-
Scripts gemmes i Djangos mediamappe (`/media`). For at sikre persistens mellem genstarter skal en *persistent volume* mountes på denne sti. Hvis dette ikke gøres, vil fejlbeskeden `<Kan ikke vise koden - upload venligst igen.>` (bl.a.) opstå, når man forsøger at åbne et scripts `Kode`-tab.
106+
Scripts gemmes i Djangos mediamappe (`/media`). For at sikre persistens mellem genstarter skal en persistent volume mountes på denne sti.
42107

43108
### Globale Scripts
109+
Globale scripts downloades fra [OS2's core-script repository](https://github.com/OS2borgerPC/os2borgerpc-core-scripts) under opstart. Konfiguration sker med:
44110

45-
Globale scripts hentes automatisk fra [OS2's core-script repository](https://github.com/OS2borgerPC/os2borgerpc-core-scripts) under opstart. Følgende miljøvariabler bruges til at konfigurere versionen:
46-
47-
- **`CORE_SCRIPT_VERSION_TAG`**
48-
Angiver den ønskede version af de globale scripts, som vises i brugergrænsefladen. Tilgængelige versioner kan ses i det linkede repository. Eksempel: `v1.2.0`.
49-
50-
- **`CORE_SCRIPT_COMMIT_HASH`**
51-
Sikrer, at versionstagget matcher det tilsvarende commit. Dette er en sikkerhedsforanstaltning, der forhindrer utilsigtede ændringer i scripts med samme versionstag.
111+
- `CORE_SCRIPT_VERSION_TAG`: Version af de globale scripts (f.eks. `v0.1.5`).
112+
- `CORE_SCRIPT_COMMIT_HASH`: Matchende commit-hash for versionen (f.eks. `5340bdc128e2de8c01def5dc50e8680399631f53`).
52113

53114
#### Sådan Finder du Commit-Hash
54-
Når du har valgt en version (fx `v1.2.0`), skal du finde det tilsvarende commit-hash:
55-
1. Gå til [repositoryets commit-historik](https://github.com/OS2borgerPC/os2borgerpc-core-scripts/commits/main).
56-
2. Find det commit, der matcher versionstagget. Dette angives typisk i commit-beskederne eller release-noterne.
57-
3. Kopiér commit-hash i fuld længde (fx `3a5c9d8f4e6e7fabc1234567890abcdef1234567`).
115+
1. Gå til [commit-historik](https://github.com/OS2borgerPC/os2borgerpc-core-scripts/commits/main).
116+
2. Find det commit, der matcher versionstagget.
117+
3. Kopiér commit-hash.
58118

59-
Alternativt kan du undlade at angive `CORE_SCRIPT_COMMIT_HASH`. Ved opstart vil admin-site logge en fejl med det forventede commit-hash, som du derefter kan kopiere.
119+
#### Opdatering af Globale Scripts
120+
1. Opdater `CORE_SCRIPT_VERSION_TAG` og `CORE_SCRIPT_COMMIT_HASH`.
121+
2. Genstart containeren.
60122

61-
#### Installation af Ny Version af Globale Scripts
62-
63-
For at installere en ny version af globale scripts:
64-
1. **Opdater miljøvariablerne**:
65-
- Sæt `CORE_SCRIPT_VERSION_TAG` til den ønskede version (fx `v1.3.0`).
66-
- Angiv det tilsvarende `CORE_SCRIPT_COMMIT_HASH`.
67-
2. **Genstart admin-site**:
68-
Genstart containeren for at aktivere ændringerne. Dette downloader og installerer den nye version af scripts.
69-
70-
**Bemærk:**
71-
- Eksisterende scripts fjernes ikke automatisk og forbliver tilgængelige. Dette sikrer, at ældre scripts stadig kan bruges af eksisterende grupper eller computere.
72-
- Hvis du ønsker at rydde op i gamle scripts, skal dette gøres manuelt (se afsnittet [Rydning af Scripts](#cleanup-scripts)).
73-
74-
Når du har installeret en ny version, vil scripts være navngivet med deres versionsnummer. Dette gør det muligt at skelne mellem forskellige versioner og sikre kompatibilitet.
75-
76-
#### <a name="cleanup-scripts"></a> Rydning af Scripts
77-
78-
For at rydde op:
79-
1. Slet scripts via SQL eller Djangos administrationsside (`/admin`).
80-
2. Fjern filer fra `/media/script_uploads`.
123+
**Bemærk:** Eksisterende scripts fjernes ikke automatisk og skal ryddes manuelt via SQL eller `/admin`.
81124

82125
---
83126

84127
## Cron Jobs
128+
Admin-site understøtter to cron jobs:
85129

86-
To cron jobs understøttes:
87-
88-
- **`check_notifications`**: Sender notifikationer. *(Forslag til schedule: `*/10 * * * *`)*
89-
- **`clean_up_database`**: Rydder op i databasen. *(Forslag til schedule: `0 19 * * 6`)*
130+
1. **`check_notifications`**: Sender notifikationer. *(Forslag: `*/10 * * * *`)*
131+
2. **`clean_up_database`**: Rydder op i databasen. *(Forslag: `0 19 * * 6`)*
90132

91-
**Sådan køres jobs via HTTP:**
133+
### Kørsel af Cron Jobs
134+
Via HTTP:
92135
```bash
93136
curl http://admin-site-url:8080/jobs/check_notifications -f
94137
curl http://admin-site-url:8080/jobs/clean_up_database -f
95138
```
96139

97-
**Baggrundsviden:** Cron jobs er implementeret som Django-commands og kaldes via `manage.py`. De kan også udføres manuelt fra en kørende container:
140+
Manuelt fra container:
98141
```bash
99142
/code/admin_site/manage.py check_notifications
100143
/code/admin_site/manage.py clean_up_database
101144
```
102145

103-
## Diverse
104-
- **`HTTPS_GUARANTEED`**: true | false (default: false)
105-
Hvis `true`, aktiveres middleware i Django, der slår sikkerhed fra og behandler HTTP som HTTPS. Brug denne parameter, hvis app'en kører bag en proxy, der terminerer TLS (f.eks. Nginx), for at undgå CSRF-fejl.
106-
Hvis parameteren ikke angives, er default-værdien `false`.
146+
---
147+
148+
## Diverse Konfigurationsparametre
149+
150+
- **`HTTPS_GUARANTEED`**:
151+
- true | false (default: false).
152+
- Aktiverer middleware for behandling af HTTP som HTTPS bag en proxy.
107153

108-
- **`PC_IMAGE_RELEASES_URL`** og\
109-
**`KIOSK_IMAGE_RELEASES_URL`**:\
110-
URL til de sider brugeren kan downloade BorgerPC ISO images. Bruges af `Images`-knappen i brugergrænsefladen.
154+
- **`PC_IMAGE_RELEASES_URL`** og **`KIOSK_IMAGE_RELEASES_URL`**:
155+
- URLs til download af BorgerPC ISO images.
156+
157+
---

0 commit comments

Comments
 (0)