Skip to content

Commit 1dbe640

Browse files
agnetemoosagnetemoos
committed
Complete rewrite
1 parent b0f9397 commit 1dbe640

File tree

1 file changed

+93
-129
lines changed

1 file changed

+93
-129
lines changed

‎docs/drift-og-hjemtagelse/installation-og-drift.md

Lines changed: 93 additions & 129 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,30 @@ mkdir -p os2borgerpc-admin
5151
# Udpakker til mappen
5252
tar -xvzf <FILNAVN>.tar.gz -C os2borgerpc-admin
5353
```
54+
55+
### Præ-installationskrav
56+
Der skal oprettes en konfigurationsfil (`.env`) med lokale systemindstillinger.
57+
58+
1. Kopier filen `.env.example.` til `.env`.
59+
60+
```bash
61+
cp .env.example .env
62+
```
63+
64+
Åbn `.env` i en text editor som f. eks. `nano`.
65+
66+
```bash
67+
nano .env
68+
```
69+
2. Tilret indstillinger til jeres lokale forhold.
70+
Som minimum skal disse indstillinger ændres.
71+
- `DOMAIN`: Dit domænenavn som skal matche dit SSL certifikat
72+
- `DB_PASSWORD`: Angiv et stærkt password
73+
- `SECRET_KEY`: Angiv en stærk nøgle.
74+
- `ALLOWED_HOSTS`: Begræns hvilke domæner/ip-adresser der skal have adgang til admin-site, hvis det er på internettet.
75+
76+
Her er en oversigt over alle systemindstillinger. XX
77+
5478
### Installation med task
5579
Kør `task`. Der vises en menu med alle tilgængelige kommandoer.
5680

@@ -76,7 +100,7 @@ Man installerer ved at køre denne kommando:
76100
```bash
77101
task install
78102
```
79-
Der er nogle præ-installations krav, der skal være opfyldt. Læs mere om præ-installationskravene her.
103+
Der er nogle præ-installations krav, der skal være opfyldt. Læs mere om præ-installationskravene her. XX
80104

81105
Tast `yes` for at fortsætte.
82106

@@ -108,27 +132,6 @@ Username: admin
108132
Password: admin
109133
```
110134

111-
### Præ-installationskrav
112-
Lokale systemindstillinger sættes i filen `.env`.
113-
114-
Kopier filen `.env.example.` til `.env`.
115-
116-
```bash
117-
cp .env.example .env
118-
```
119-
120-
Åbn `.env` i en text editor som f. eks. `nano`.
121-
122-
```bash
123-
nano .env
124-
```
125-
126-
Af sikkerhedshensyn opdaterer ALTID disse indstillinger med dine egne værdier:
127-
- `DOMAIN`: Dit domænenavn som skal matche dit SSL certifikat
128-
- `DB_PASSWORD`: Angiv et stærkt password
129-
- `SECRET_KEY`: Angiv en stærk nøgle.
130-
131-
132135
### Oversigt over systemindstillinger
133136

134137
| Variabel | Forklaring | Standardværdi | Påkrævet |
@@ -145,7 +148,7 @@ Af sikkerhedshensyn opdaterer ALTID disse indstillinger med dine egne værdier:
145148
| `CORE_SCRIPT_COMMIT_HASH` | Hver version af globale scripts har et matchende commit-hash. Find det i release beskrivelsen her: https://github.com/OS2borgerPC/os2borgerpc-core-scripts/releases | `a96d19567bf5c002c76d16cf80f6c894c2af499` | Ja |
146149
| `PC_IMAGE_RELEASES_URL` | URL til download af BorgerPC ISO images | `https://github.com/OS2borgerPC/os2borgerpc-image/releases` | Nej |
147150
| `KIOSK_IMAGE_RELEASES_URL` | URL til download af Kiosk ISO images | `https://github.com/OS2borgerPC/os2borgerpc-kiosk-image/releases` | Nej |
148-
| `DEBUG` | Aktiverer debug-tilstand i Django | `True` | Nej |
151+
| `DEBUG` | Aktiverer debug-tilstand i Django | `False` | Nej |
149152
| `SECRET_KEY` | Hemmelig nøgle til Django | `v3rys1kr3t` | Ja |
150153
| `ADMIN_USERNAME` | Brugernavn for admin-bruger | `admin` | Ja |
151154
| `ADMIN_EMAIL` | Email for admin-bruger. Kan ændres i GUI efter installation (Hovedmenu > Brugere). | `[email protected]` | Ja |
@@ -158,143 +161,104 @@ Af sikkerhedshensyn opdaterer ALTID disse indstillinger med dine egne værdier:
158161
| `CITIZEN_LOGIN_API_VALIDATOR`| Validator for citizen login API | `system.utils.always_validate_citizen` | Nej |
159162
| `USE_X_FORWARDED_HOST` | Aktiverer brug af `X-Forwarded-Host` header bag proxy | `True` | Nej |
160163
| `SECURE_PROXY_SSL_HEADER` | Header til at indikere SSL bag proxy | `('HTTP_X_FORWARDED_PROTO', 'https')` | Nej |
164+
| `HTTPS_GUARANTEED` | Aktiverer middleware for behandling af HTTP som HTTPS bag en proxy. Sæt til `true` hvis du er bag en reverse proxy, der håndterer SSL. | `false` | Nej |
161165

162166

163167
---
164-
## Introduktion
165168

169+
### On premice drift
170+
OS2BorgerPC Admininstartionssitet egener sig meget fint til hjemtagelse. Som regel er det ret få medarbejdere der skal tilgå systemet, og man kan derfor vælge at placere serveren på et internt netværk frem for internettet. Arbejdes der hjemme kan sitet evt. nås via VPN. Det gør sikkerheden lettere at håndtere.
166171

167-
**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.
172+
Nedetid på OS2BorgerPC Administrationssitet påvirker ikke BorgerPC-maskinerne. De kører fint videre, selvom serveren ikke er tilgængelig. Skulle serveren drille en dag hvor jeres system administrator holder fridag, mærkes det ikke på biblioteket, i jobcenteret eller hvor ellers jeres BorgerPC maskinerne står.
168173

169-
Konfiguration sker via miljøvariabler (beskrevet nedenfor) og omfatter desuden specifikationer for driftskrav. En `compose.yaml`-fil leveres som reference til udvikling og konfiguration.
174+
Sønderborg Kommune har selv hostet OS2BorgerPC Administrationssitet i 5 år med gode erfaringer.
170175

171-
**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.
176+
### Automatiserede Jobs (Cron Jobs)
177+
Cron er en facilitet indbygget i Ubuntu ,som kan bruges til at planlægge kørsler af jobs.
172178

173-
---
179+
På et OS2BorgerPC Administrationssite er der to jobs, der skal køres regelmæssigt:
180+
- Et der udsender email notifikationer ved sikkerhedshændelser
181+
- Et der rydder op i forældede data i databasen
174182

175-
## Drift Anbefalinger
176-
177-
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:
178-
179-
### Drift Opsætning
180-
1. **Undgå brug af `docker-compose` i produktion:**
181-
- `docker-compose` er velegnet til udvikling, men anbefales ikke til produktion.
182-
- Brug en orkestreringsløsning som Kubernetes eller Docker Swarm til at håndtere containere.
183-
184-
2. **Ønskes brug af docker-compose alligevel eller sammen med Docker Swarm:**
185-
- Lav ny docker-compose fil med udgangspunkt i `compose.yaml`
186-
- Fjern unødvendige services som `frontend` og tilpas `cron-service` som beskrevet nedenfor.
187-
- Konfigurer admin-site til at pege på et specifikt Docker-image-tag, f.eks.:
188-
```yaml
189-
image: ghcr.io/os2borgerpc/os2borgerpc-admin-site:<specific-tag>
190-
```
191-
- Indstil miljøvariabler i henhold til dokumentationen.
192-
193-
3. **Volumenhåndtering:**
194-
- Sørg for at mount persistente volumes til `/media` for at sikre, at scripts og andre uploads bevares mellem genstarter.
195-
- Eksempel:
196-
```yaml
197-
volumes:
198-
- admin-media:/media
199-
```
200-
201-
4. **Sikkerhed:**
202-
- Angiv en stærk `SECRET_KEY` i miljøvariablerne.
203-
- Begræns `ALLOWED_HOSTS` til de domæner, der skal have adgang til admin-site.
204-
205-
### Opgradering af Admin-Site
206-
1. **Forberedelse:**
207-
- Gennemgå release-notes for den nye version.
208-
- Test opgraderingen i et udviklings- eller staging-miljø.
209-
210-
2. **Opdatering:**
211-
- Opdater Docker-image-tagget til den ønskede version i din orkestreringsopsætning.
212-
- Genstart admin-site-containere for at anvende ændringerne.
213-
214-
3. **Validering:**
215-
- Bekræft, at opgraderingen er succesfuld ved at teste kernefunktionalitet.
216-
- Tjek logfiler for fejl eller advarsler.
217-
218-
### Fejlfinding
219-
- Hvis der opstår problemer under opgradering, kan du rulle tilbage til det tidligere Docker-image-tag.
220-
- Kontroller logfiler i admin-site-containere for detaljerede fejlmeddelelser.
183+
2. Gå ind i crontab hvor cronjobs registreres:
184+
```bash
185+
crontab -e
186+
```
187+
Måske bliver du bedt om at vælge, hvilken tekst editor du vil benytte. Vælg Nano, da den er mest brugervenlig.
221188

222-
---
189+
3.
190+
Indsæt følgende linjer i crontab:
223191

224-
## Bootstrapping
225-
For at initialisere admin-site og få adgang til Djangos administrationsside (`<base URL>/admin`), skal en admin-bruger oprettes med følgende miljøvariabler:
192+
HUSK! Udskift `demo.os2borgerpc.dk` med dit eget domænenavn:
226193

227-
- `ADMIN_USERNAME`
228-
- `ADMIN_PASSWORD`
229-
- `ADMIN_EMAIL`
194+
```bash
195+
# Run check_notifications every 10 minutes
196+
*/10 * * * * curl http://demo.os2borgerpc.dk:8080/jobs/check_notifications -f
230197

231-
**Bemærk:** `ADMIN_EMAIL` anvendes af Djangos indbyggede brugerhåndtering. Den oprettede admin-bruger kan også administrere sites og klienter.
198+
# Run clean_up_database once a week (Sunday at midnight)
199+
0 0 * * 0 curl http://demo.os2borgerpc.dk:8080/jobs/clean_up_database -f
232200

233-
---
201+
```
202+
Har du brug for at køre cron jobbene manuelt kan det gøres via kommandoen:
203+
```bash
204+
task cron
205+
```
234206

235-
## Database
236-
Konfiguration af databaseforbindelsen sker via følgende miljøvariabler:
207+
### Persistens og backup
237208

238-
- `DB_HOST`
239-
- `DB_PORT`
240-
- `DB_USER`
241-
- `DB_PASSWORD`
242-
- `DB_NAME`
209+
For at sikre, at scripts og andre uploads bevares mellem genstarter og ved opgradering gemmes de på et persistent volume, der hedder `admin-media`.
243210

244-
Se `compose.yaml` for eksempler.
211+
Volume data ligger på denne sti. Stien kan variere lidt alt efter hvordan docker blev installeret.
212+
```bash
213+
/var/lib/docker/volumes/os2borgerpc-admin-site-deployment_admin-media
214+
```
245215

246-
---
216+
Tilsvarende ligger databasen på et persistent volume, der hedder `postgres-data`.
217+
```bash
218+
/var/lib/docker/volumes/os2borgerpc-admin-site-deployment_postgres-data
219+
```
220+
Man kan lave et database dump via task-værktøjet:
221+
```bash
222+
task db_dump
223+
```
247224

248-
## Scripts
249-
Scripts gemmes i Djangos mediamappe (`/media`). For at sikre persistens mellem genstarter skal en persistent volume mountes på denne sti.
225+
Ønsker man daglige db-dumps til backup formål, kan et cron-job opsættes.
250226

251-
### Globale Scripts
252-
Globale scripts downloades fra [OS2's core-script repository](https://github.com/OS2borgerPC/os2borgerpc-core-scripts) under opstart. Konfiguration sker med:
227+
HUSK! Tilret stien hen til installationsmappen. Udskift `mitbrugernavn` med dit eget.
228+
229+
```bash
230+
0 2 * * * cd /home/mitbrugernavn/os2borgerpc-admin-site-deployment && task backup_db
231+
0 2 * * * find /home/mitbrugernavn/os2borgerpc-admin-site-deployment -mtime +10 -type f -delete
232+
```
253233

254-
- `CORE_SCRIPT_VERSION_TAG`: Version af de globale scripts (f.eks. `v0.1.5`).
255-
- `CORE_SCRIPT_COMMIT_HASH`: Matchende commit-hash for versionen (f.eks. `5340bdc128e2de8c01def5dc50e8680399631f53`).
234+
Eksemplet her laver et db_dump hver nat kl. 02:00. Samtidig slettes db_dumps der er ældre end 10 dage.
256235

257-
#### Sådan Finder du Commit-Hash
258-
1. Gå til [commit-historik](https://github.com/OS2borgerPC/os2borgerpc-core-scripts/commits/main).
259-
2. Find det commit, der matcher versionstagget.
260-
3. Kopiér commit-hash.
261236

262-
#### Opdatering af Globale Scripts
263-
1. Opdater `CORE_SCRIPT_VERSION_TAG` og `CORE_SCRIPT_COMMIT_HASH`.
264-
2. Genstart containeren.
237+
### Globale Scripts
238+
OS2BorgerPC Admin fødes uden globale scripts. I forbindelse med opstart udfyldes globale scripts med indholdet af [os2borgerpc-core-scripts](https://github.com/OS2borgerPC/os2borgerpc-core-scripts/releases).
265239

266-
**Bemærk:** Eksisterende scripts fjernes ikke automatisk og skal ryddes manuelt via SQL eller `/admin`.
240+
Hvilken version af script-pakken, der indlæses under opstart, styres via disse to variabler:
267241

268-
---
242+
- `CORE_SCRIPT_VERSION_TAG`: Version af de globale scripts (f.eks. `v1.0.1`).
243+
- `CORE_SCRIPT_COMMIT_HASH`: Matchende commit-hash for versionen (f.eks. `6a96d19567bf5c002c76d16cf80f6c894c2af499`).
244+
245+
246+
#### Opdatering af Globale Scripts
247+
Vil man indlæse en nyere version af core-scripts er det så simpelt som at opdatere de to variable og genstarte.
269248

270-
## Cron Jobs
271-
Admin-site understøtter to cron jobs:
249+
Det kan gøres via
250+
1. Opdater `CORE_SCRIPT_VERSION_TAG` og `CORE_SCRIPT_COMMIT_HASH`.
272251

273-
1. **`check_notifications`**: Sender notifikationer. *(Forslag: `*/10 * * * *`)*
274-
2. **`clean_up_database`**: Rydder op i databasen. *(Forslag: `0 19 * * 6`)*
252+
Man finder commit hash øverst i release notes.
253+
https://github.com/OS2borgerPC/os2borgerpc-core-scripts/releases
275254

276-
### Kørsel af Cron Jobs
277-
Via HTTP:
255+
2. Genstart. F. eks. via
278256
```bash
279-
curl http://admin-site-url:8080/jobs/check_notifications -f
280-
curl http://admin-site-url:8080/jobs/clean_up_database -f
257+
task stop
281258
```
282-
283-
Manuelt fra container:
284259
```bash
285-
/code/admin_site/manage.py check_notifications
286-
/code/admin_site/manage.py clean_up_database
260+
task up
287261
```
288262

289-
---
290-
291-
## Diverse Konfigurationsparametre
292-
293-
- **`HTTPS_GUARANTEED`**:
294-
- true | false (default: false).
295-
- Aktiverer middleware for behandling af HTTP som HTTPS bag en proxy.
296-
297-
- **`PC_IMAGE_RELEASES_URL`** og **`KIOSK_IMAGE_RELEASES_URL`**:
298-
- URLs til download af BorgerPC ISO images.
263+
**Bemærk:** Eksisterende scripts fjernes ikke automatisk og skal ryddes manuelt via SQL eller `/admin`.
299264

300-
---

0 commit comments

Comments
 (0)