From ff46002a895a2cc8f0e637b7cce925302b7902da Mon Sep 17 00:00:00 2001 From: Aleix Quintana Alsius Date: Tue, 18 Apr 2023 13:55:51 +0000 Subject: [PATCH 01/18] Translate install.sh --- docs/install.md | 149 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 docs/install.md diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 0000000..2082708 --- /dev/null +++ b/docs/install.md @@ -0,0 +1,149 @@ +# Installation + +## Requirements + +GNU/Linux [debian](https://debian.org) based distribution able to run docker-compose v1.28 or newer. + +## Configuration + +It's a good idea to familiarize with the settings available in [`dd.conf.sample`][dd.conf.sample], which is the main configuration file. + +[dd.conf.sample]: https://gitlab.com/DD-workspace/DD/-/blob/main/dd.conf.sample + +The installation process must be done using `dd-install.sh`, answering the questions and/or passing environment variables, it will write a dd.conf based on the dd.conf.sample. As example: + +``` +> DD_NETWORK_MTU=1450 ./dd-install.sh +``` +## Guided install + +Using the script [`dd-install.sh`][dd-install.sh] without any arguments will proceed with the guided installation. + +[dd-install.sh]: https://dd-work.space/docs/dd-install.sh + +The wizard will guide you through the installation process. it will ask you a sequence of questions, to install and configure for the first time. + +Once installation is complete, you can proceed with the [post-installation](post-install.md). + +### Guided example + +```bash +# We obtain dd-install.sh +> wget https://dd-work.space/docs/dd-install.sh -O dd-install.sh +# Make it executable +> chmod +x dd-install.sh +# And run it +> ./dd-install.sh +Interactive install detected! +Please follow the instructions carefully: + +Under which DOMAIN will you install DD? example.org + + +You will need to setup DNS entries for: +- [ ] moodle.dd.004.es +- [ ] nextcloud.dd.004.es +- [ ] wp.dd.004.es +- [ ] oof.dd.004.es +- [ ] sso.dd.004.es +- [ ] pad.dd.004.es +- [ ] admin.dd.004.es +- [ ] api.dd.004.es +- [ ] correu.dd.004.es + + +What is the short title of the DD instance? [DD] +What is the full title of the DD instance? [DD] DD at example.org +Do you want to use Let's Encrypt certificates? [Y/n] Y +Which email will you use for Let's Encrypt notifications? letsencrypt@example.org +Generate a certificate for example.org? (neds the DNS entry) [y/N] N +Path to the logo's PNG file (optional): +Path to the background's PNG file (optional): +About to install with following information: + +DOMAIN=example.org +TITLE_SHORT=DD +TITLE=DD at example.org +LETSENCRYPT_DNS=example.org +LETSENCRYPT_EMAIL=letsencrypt@example.org +LETSENCRYPT_DOMAIN_ROOT=false + +Custom logo in PNG (if requested): +Custom background in PNG (if requested): +Is this correct? proceed with the install? [Y/n] Y +``` +
Logos +Optionally you can define the logos by placing the .png files on the server and indicate their path when the installer requests them. +
+ +
Pre-existing certificate +You can use your own certificate, being it a single, wildcard or SAN certificate. You can read more in the [wildcard](wildcard.md) section. +
+ +## Unattended install + +The installer accepts all the variables existing in [`dd.conf.sample`][dd.conf.sample] as environment variables using the `DD_` prefix to distinct of other environment variables. + +For example, the variable `DOMAIN` can be pre-configured with the environment variable `DD_DOMAIN`. +Read the next example. + +If `DD_DOMAIN` is defined, the unattended installation will be started using values from environment variables. +Otherwise, without defining `DD_DOMAIN`, it will proceed with the unattended installation. + +Take note that when using the unattended mode, the dns records must resolve to your server ip address. You will need to setup DNS records for: + + - moodle.${DD_DOMAIN} + - nextcloud.${DD_DOMAIN} + - wp.${DD_DOMAIN} + - oof.${DD_DOMAIN} + - sso.${DD_DOMAIN} + - pad.${DD_DOMAIN} + - admin.${DD_DOMAIN} + - api.${DD_DOMAIN} + +> It is worth noting that this way of installation can be automated with provisioning tools such as [Ansible][ansible], [cdist][cdist] or [Puppet][puppet]. + +[ansible]: https://ansible.com +[cdist]: https://cdi.st +[puppet]: https://puppet.com + +Once installation is complete, you can proceed with the [post-installation](post-install.md). + +### Unattended example + +```bash +> export DD_DOMAIN="example.org" +> export DD_TITLE="DD at example.org" +> export DD_TITLE_SHORT="DD" +> export DD_LETSENCRYPT_DNS="example.org" +> export DD_LETSENCRYPT_EMAIL="letsencrypt@example.org" +# +# +# We obtain dd-install.sh +> wget https://dd-work.space/docs/dd-install.sh -O dd-install.sh +# Make it executable +> chmod +x dd-install.sh +# And run it +> ./dd-install.sh +``` + +
Logos +Optionally you can define the logos by placing the .png files on the server and pointing the environment variables DDIMG_LOGO_PNG and +DDIMG_BACKGROUND_PNG to their path. +
+ +## Manual install + +The manual install is documented in file [`dd-install.sh`][repo-dd-install.sh] from line : + +[repo-dd-install.sh]: https://gitlab.com/DD-workspace/DD/-/blob/main/dd-install.sh + +```bash +# +# START MANUAL INSTALL +# +``` + +You will find comments for each step along with their respective commands. + +Once installation is complete, you can proceed with the [post-installation](post-install.md). From 363ec4b0e861cd66f8a8d25a982bbd4d84ed6759 Mon Sep 17 00:00:00 2001 From: Aleix Quintana Alsius Date: Fri, 21 Apr 2023 12:05:01 +0000 Subject: [PATCH 02/18] Translate customising --- docs/customising.md | 70 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 docs/customising.md diff --git a/docs/customising.md b/docs/customising.md new file mode 100644 index 0000000..57aff9b --- /dev/null +++ b/docs/customising.md @@ -0,0 +1,70 @@ +# Customizing + +## Megamenu links + +The [Megamenu][megamenu-internal] has two parts: + +- [Internal / system][megamenu-internal] +- [External / configurable][megamenu-external] + +[megamenu-internal]: https://dd.digitalitzacio-democratica.xnet-x.net/manual-usuari/menu-principal-dd/ +[megamenu-external]: https://dd.digitalitzacio-democratica.xnet-x.net/manual-usuari/eines-externes-megamenu/ + +Only [External links in Megamenu][megamenu-external] can be modified using the interface, [internal links][megamenu-internal] such as `https://admin.DOMAIN` cannot be modified using the interface. + +In both cases a customization and provisioning can be made editing files `custom/menu/custom.yaml` and +`custom/menu/system.yaml`. + +The examples of these files are in `custom.sample/menu/custom.yaml` and `custom.sample/menu/system.yaml`. + +### `custom/menu/system.yaml` + +When editing `custom/menu/system.yaml`, keep in mind that depending on the `href` value and if is defined the `subdomain`, each link will be generated different. + +Also note that relative urls must start with `/` or `#`. + +```yaml +# Example of apps_internal in custom/menu/system.yaml +apps_internal: +# Generates the link https://DOMAIN/about +- href: /about + icon: fa fa-rss + name: About + shortname: a +# Generates the link https://moodle.DOMAIN/courses +- subdomain: moodle + href: /courses + icon: fa fa-graduation-cap + name: Courses + shortname: courses +# Generates the link https://external-url.com +# because url is absolute +- href: https://external-url.com + icon: fa fa-book + name: external-url.com + shortname: external url + +``` + +## Peu de pàgina en el login + +The footer is part of the Keycloak login theme, to modify it, it needs to use a theme based on 'dd' theme. + +To make things easier, in directory `dd-sso/docker/keycloak/themes` there are these subdirectories: + +- `dd-custom`: an empty directory, what is created here, keycloak will use as a new `dd-custom` theme. +- `dd-custom.sample`: an example of how the theme `dd-custom` would be prepared in order to replace the footer. + +So, to customize the footer, you need to copy the contents of `dd-custom.sample` to `dd-custom`, then edit `dd-custom/login/dd-footer.ftl` to suit our needs. + +Once this is done, in the keycloak administration interface you need to pick `dd-custom` as a login theme: + +`https://sso.DOMAIN/auth/admin/master/console/#/realms/master/theme-settings` + +> **Note:** dd-custom directory never will be updated, so it is your responsibility +> to review the chnges with maintained `dd` theme, the contents of directory `dd-custom` +> and contents of `dd-custom.sample` to make your customization compatible. + +## Integració amb altres eines + +It is possible to integrate DD with other tools, read about it in [integrations](integrations.md) section. \ No newline at end of file From 5073b6d4dc2bdaa760961f1b47d29232fe082c94 Mon Sep 17 00:00:00 2001 From: Aleix Quintana Alsius Date: Fri, 21 Apr 2023 12:20:51 +0000 Subject: [PATCH 03/18] translate integrations --- docs/integrations.md | 63 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 docs/integrations.md diff --git a/docs/integrations.md b/docs/integrations.md new file mode 100644 index 0000000..a6fdce2 --- /dev/null +++ b/docs/integrations.md @@ -0,0 +1,63 @@ +# Integrations + +The dd can be integrated with other systems using their APIs. + +## Autentication + +All requests must be authenticated with a [Json Web Token (JWT)][jwt], +and must be signed with the `API_SECRET` (defined in `dd.conf`). + +This authentication is done with the `Authentication` http header. + +
+Read details +```sh +> curl -H "Authorization: bearer ${jwt}" https://admin.DOMAIN/ddapi/roles +[ + { + "keycloak_id": "9325ad99-7e04-4c31-9768-5512e1564160", + "id": "admin", + "name": "admin", + "description": "${role_admin}" + }, + { + "keycloak_id": "c6c8a73e-51fc-4716-831d-1dfc0e0b62b0", + "id": "manager", + "name": "manager", + "description": "Realm managers" + }, + { + "keycloak_id": "24d7977e-da83-4591-8e13-0fac3126afa1", + "id": "student", + "name": "student", + "description": "Realm students" + }, + { + "keycloak_id": "d6699c41-13d5-4623-bdca-e5f2775474ed", + "id": "teacher", + "name": "teacher", + "description": "Realm teachers" + } +] +``` + +Where JWT can be generated, e.g. using python-jose: + +```python +import os +from jose import jws +t = jws.sign({}, os.environ["API_SECRET"], algorithm="HS256") +print(t) +``` + +Other programming languages have similar ways of generating tokens. +
+ +[jwt]: https://jwt.io/ +[jose]: https://python-jose.readthedocs.io/ + +## API Notable + +![Projecte NotaBLE](assets/images/notable.jpg) + +!!swagger ddapi.json!! From 04bfebf2e981dfb60347bce453ee70360a69ab7c Mon Sep 17 00:00:00 2001 From: Aleix Quintana Alsius Date: Fri, 21 Apr 2023 21:38:59 +0000 Subject: [PATCH 04/18] PostInstall translation --- docs/post-install.md | 100 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 docs/post-install.md diff --git a/docs/post-install.md b/docs/post-install.md new file mode 100644 index 0000000..fa4bd02 --- /dev/null +++ b/docs/post-install.md @@ -0,0 +1,100 @@ +# Post-installation instructions + +Although the [installer](install.md) automates most of the configuration, some manual steps are still required. + +## Access without SAML + +Once installed, services are accessible without SAML, it can be useful to complete or check some configuration. + +login detail are defined in `dd.conf`. + +| Service | Variables | Login without SAML | +| ------ | --------- | ---------------- | +| Moodle | `MOODLE_ADMIN_*` |`https://moodle.DOMAIN/login/index.php?saml=off` | +| Nextcloud | `NEXTCLOUD_ADMIN_*` | `https://nextcloud.DOMAIN/login?direct=1` | +| Wordpress | `WORDPRESS_ADMIN_*` | `https://wp.DOMAIN/wp-login.php?normal` | +| Keycloak | `KEYCLOAK_*` | `https://sso.DOMAIN/auth/admin/master/console` | +| Admin | `DDADMIN_*` | `https://admin.DOMAIN` | + + +## SAML user for testing + +To be able to check all services you need to create a SAML user. +This is done in administration application in https://admin.DOMAIN. +There follow next steps: + +- Create a group, for example: "teachers" +- Click Resync button. +- Go to groups and verify that group exists. +- Go to users and create a "teacher01" of group "teachers" with role "teacher" + +## Activate WAF + +If you wish, you can enable Web Application Firewall/Modsecurity following [these instructions](waf-modsecurity.md). + +## Nextcloud common templates (Optional) + +It is possible to set common templates to all users: + +![](img/snapshot/Y!-rq;7GxjTW.png) + + +## Integration Moodle-Nextcloud + +The integration between Moodle and Nextcloud is not automated, next steps must be followed once DD installation has finished. + + + +### Create a Oauth client in Nextcloud + +![](img/snapshot/3ICWP5X.png) + +- Name: moodle +- URI: https://moodle.test1.digitaldemocratic.net/admin/oauth2callback.php + +The created **Client ID** and **Secret**, must be added in Moodle's OAuth2. + + +### Create the service OAuth2 in Moodle + +https://moodle.test1.digitaldemocratic.net/admin/tool/oauth2/issuers.php + +Create new Nextcloud service + +![](img/snapshot/mkM8JN1.png) + +Configure as this: + +- Name: Nextcloud +- Client Id: **Client ID** +- Client Secret: **Secret** +- [OK] Authenticate token requests via HTTP headers +- Service base URL: https://nextcloud.test1.digitaldemocratic.net + +![](img/snapshot/KBV5ys2.png) + +To test that it works, click on the next icon: +![](img/snapshot/XLQNA9i.png) + +And follow the authentication steps that indicates Nextcloud. A green tick, means that configuration is ok and it is working. + +### Enable repository in Moodle +3. Go to 'Manage repositories' https://moodle.test1.digitaldemocratic.net/admin/repository.php + +Enable and make it visible + +Go to Nextcloud repository configuration: + +![](img/snapshot/JGRbAJF.png) + +Enable both options and save: + +![](img/snapshot/buRSMwg.png) + +Create an instance of the repository with these values: + +- Name: Nextcloud +- Issuer: Select the OAuth2 created earlier +- Folder: '' +- Supported files: Internal and External +- Return type: Internal \ No newline at end of file From fa765bbc66a9d261c0d9984e81215d743c662b0e Mon Sep 17 00:00:00 2001 From: Aleix Quintana Alsius Date: Fri, 21 Apr 2023 21:48:54 +0000 Subject: [PATCH 05/18] Stashed Contribute translation --- docs/contributing.md | 143 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 143 insertions(+) create mode 100644 docs/contributing.md diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000..dbdee73 --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,143 @@ +# Contribute + +DD is free software under AGPL3+ license, and contributions are welcome. + +## Source code + +The source code repository and techincal documentation are in: +[https://gitlab.com/DD-workspace/DD](https://gitlab.com/DD-workspace/DD) + +## DD Architecture + +Per molts canvis serà necessari que us familiaritzeu amb l'arquitectura del DD. + +El diagrama d'arquitectura del DD es troba al repositori en format +[editable][diagramedit], i hi podeu contribuir com amb qualsevol altre canvi. + +![DD Workspace for education - Arquitectura](assets/diagram/dd_workspace_education.png) + +[diagramedit]: https://gitlab.com/DD-workspace/DD/-/tree/main/docs/assets/diagram + + +## Metodología: Desenvolupament Adaptatiu de Software (ASD) + +Per tal d'organitzar-nos fem servir la metodologia de +Desenvolupament Adaptatiu de Software +(o ASD per les seves sigles en anglès Adaptive Software Development). + +Aquesta metodologia posa el focus en les dinàmiques d'equips auto-organitzats, +la col·laboració interpersonal i l'aprenentatge individual i dels equips +de manera que ens permet integrar fàcilment la naturalesa *Open Source* +del **DD** amb els cicles de feedback o d'actualització a les escoles que fan +part del projecte Pilot i les necessitats tècniques del projecte. + +ASD ajuda a construir sistemes de software complexes, en el nostre cas un +entorn educatiu digital. + +S'organitza en cicles iteratius de 3 fases: + +1. **Especulació**: En aquesta fase planegem tenint en compte les limitacions i + necessitats del projecte, dels usuaris, etc. (en forma de [Issues][issues], + feedback o incidències) per tal de definir els cicles que volem. +2. **Col·laboració**: En aquesta fase ens organitzem i treballem conjuntament, + sempre tenint en compte que les persones que treballen juntes han de: + + - Criticar sense hostilitat + - Assistir sense ressentiment + - Treballar el més fortament possible + - Tenir o obtenir les habilitats necessàries + - Comunicar els problemes que eviten trobar una solució efectiva + +3. **Aprenentatge**: Tant si arribem al resultat desitjat com si no, aquest + procés haurà incrementat l'enteniment del projecte i les tecnologies + associades de totes les persones que hi participen. + En aquest procés una part crucial són les [Merge Request][mr] i les revisions + (**Reviews**) associades, així com la comunicació de l'equip que hi treballa. + +Aplicant aquesta metodologia de manera iterativa anem millorant el projecte +incrementalment. + +Alguns recursos online gratuïts per familiaritzar-s'hi són: + +- [https://users.exa.unicen.edu.ar/catedras/agilem/cap23asd.pdf](https://users.exa.unicen.edu.ar/catedras/agilem/cap23asd.pdf) +- [https://www.geeksforgeeks.org/adaptive-software-development-asd/](https://www.geeksforgeeks.org/adaptive-software-development-asd/) +- [https://yewtu.be/watch?v=HXJWwxL2N5A](https://yewtu.be/watch?v=HXJWwxL2N5A) +- [https://files.ifi.uzh.ch/rerg/amadeus/teaching/seminars/seminar_ws0304/06_Eberle_ASD_Folien.pdf](https://files.ifi.uzh.ch/rerg/amadeus/teaching/seminars/seminar_ws0304/06_Eberle_ASD_Folien.pdf) + +### En la pràctica + +- Has detectat un problema? Ajuda'ns reportant un [problema/issue][issues]. +- Vols afegir un parche? Et pot ser útil l'apartat dels controls de qualitat + tot seguit. En funció de la complexitat dels teus canvis: + + - Si en són senzills, obre directament una [Merge Request][mr] + explicant el que vols afegir i per què. + D'aquesta manera iniciarà el procés de **revisió/review**. + - Si en són més complicats, potser posa't en contacte abans perquè puguem + avaluar si la teva solució és la que més s'adjusta al projecte. + Una bona manera de fer-ho és obrint una [issue][issues] explicant el que + vols fer, per què i com. + +- Col·labores habitualment amb el DD? Ajuda amb les revisions de codi de les + [Merge Request][mr] pendents, tenint en compte els controls de qualitat. + +[issues]: https://gitlab.com/DD-workspace/DD/-/issues +[mr]: https://gitlab.com/DD-workspace/DD/-/merge_requests + +## Controls de qualitat + +### Continuous Integration + +Per simplificar la feina de revisió de codi i assegurar una certa qualitat del +que entra al repositori: + +- Ningú pot fer `push` a la branca principal (`main`) directament. + Sempre és necessari passar pel procés de [Merge Request][mr] i review. +- Disposem d'una instància de [buildbot][buildbot] com a Continuous Integration + (a `ci.dd-work.space`, login amb GitLab) que reacciona a esdeveniments de + tipus `push` al repositori principal, i de tipus [Merge Request][mr] des de + qualsevol repositori. + - Quan es tracta d'un [Merge Request][mr], només s'executen comprovacions + de estàtiques, que no executen el codi del repositori. + Això és per evitar abús de tipus mineria de criptomonedes i demés. + Aquestes comprovacions ara mateix són: + [ShellCheck][sc] per scripts de shell, [mkdocs][mkdocs] per comprovar + que la documentació es genera correctament, i aviat hi afegirem linters i + comprovadors estàndard de Python. + - Quan es tracta d'un esdeveniment `push` al repositori principal, + addicionalment a les comprovacions anteriors, es comença el procés + d'instal·lació des de zero en una màquina virtual. + Això ajuda a detectar quan s'introdueixen problemes i a assegurar que el + DD es pot instal·lar correctament. +- Els membres del grup `DD-workspace` a GitLab tenen permisos d'administració a + la instància de Buildbot, això els permet iniciar builds manualment o + cancel·lar tasques si és necessari. + +### Checklist + +Abans d'aprovar una Merge Request, hem de fer les següents comprovacions als +canvis que es volen introduir: + +- [ ] Passen les comprovacions a la CI +- [ ] Les modificacions introduïdes són necessàries, solucionen un problema + real, o milloren la mantenibilitat del projecte +- [ ] Es consideren i debaten les implicacions de **seguretat** +- [ ] Es consideren i debaten les implicacions de **mantenibilitat** +- [ ] Es revisen possibles regressions de funcionalitat +- [ ] No s'utilitzen dades reals en les proves +- [ ] El resultat de la instal·lació des de zero en el CI és satisfactori + - [ ] És possible crear i modificar grups i usuaris + - [ ] És possible iniciar sessió amb SSO a Moodle, Nextcloud i Wordpress +- [ ] Es respecta el [Principi de mínima sorpresa (Principle Of Least Attonishment / POLA)][pola] + - [ ] Això inclou que es respectin les configuracions explícites + dels operadors (`dd.conf`) + - [ ] Les funcionalitats noves que puguin tenir efectes negatius, només + s'aplicaran per defecte, quan els operadors hagin tingut temps + suficient de desactivar-les abans + + +Si algun d'aquests passos falla, procedirem a ajudar a qui ha proposat els +canvis a solucionar els inconvenients. + +[buildbot]: https://buildbot.net +[pola]: https://en.wikipedia.org/wiki/Principle_of_least_astonishment From 32e2db0cf2ac71b0f36be70aca188c4f4a1a864d Mon Sep 17 00:00:00 2001 From: Aleix Quintana Alsius Date: Sat, 22 Apr 2023 16:18:24 +0000 Subject: [PATCH 06/18] WIP contfibuting translation --- docs/contributing.md | 54 ++++++++++++++++---------------------------- 1 file changed, 19 insertions(+), 35 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index dbdee73..1058fef 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -4,60 +4,44 @@ DD is free software under AGPL3+ license, and contributions are welcome. ## Source code -The source code repository and techincal documentation are in: +The source code repository and techincal documentation is available at: [https://gitlab.com/DD-workspace/DD](https://gitlab.com/DD-workspace/DD) ## DD Architecture -Per molts canvis serà necessari que us familiaritzeu amb l'arquitectura del DD. - -El diagrama d'arquitectura del DD es troba al repositori en format -[editable][diagramedit], i hi podeu contribuir com amb qualsevol altre canvi. +Code modifications will require you to familiarize yourself with DD architecture. ![DD Workspace for education - Arquitectura](assets/diagram/dd_workspace_education.png) +**Note** This DD architecture diagram can be found in code respository in [editable][diagramedit] format. Like the rest of the whole code, you can suggest modifications + [diagramedit]: https://gitlab.com/DD-workspace/DD/-/tree/main/docs/assets/diagram -## Metodología: Desenvolupament Adaptatiu de Software (ASD) +## Methodology: Adaptive software development(ASD) -Per tal d'organitzar-nos fem servir la metodologia de -Desenvolupament Adaptatiu de Software -(o ASD per les seves sigles en anglès Adaptive Software Development). +In order to organize contributions, adaptive software development methodology(ASD) is used. -Aquesta metodologia posa el focus en les dinàmiques d'equips auto-organitzats, -la col·laboració interpersonal i l'aprenentatge individual i dels equips -de manera que ens permet integrar fàcilment la naturalesa *Open Source* -del **DD** amb els cicles de feedback o d'actualització a les escoles que fan -part del projecte Pilot i les necessitats tècniques del projecte. +This methodology focuses on self-organized team dynamics, interpersonal collaboration, and individual and team learning in a way that allows integrate the *Open Source* nature of **DD** with feedback or update cycles in the schools that are part of the pilot project and the technical needs of the project. -ASD ajuda a construir sistemes de software complexes, en el nostre cas un -entorn educatiu digital. +ASD helps build complex software systems, in our case a digital educational environment. -S'organitza en cicles iteratius de 3 fases: +It is organized in iterative cycles of three phases : -1. **Especulació**: En aquesta fase planegem tenint en compte les limitacions i - necessitats del projecte, dels usuaris, etc. (en forma de [Issues][issues], - feedback o incidències) per tal de definir els cicles que volem. -2. **Col·laboració**: En aquesta fase ens organitzem i treballem conjuntament, - sempre tenint en compte que les persones que treballen juntes han de: +1. **Speculation**: In this phase a plan is made taking into account limitations and needs of the project, users, etc. writing issues, feedback or failures, in order to define the cycles. +2. **Collaboration**: In this phase we organize and work together, always taking care that working people must: - - Criticar sense hostilitat - - Assistir sense ressentiment - - Treballar el més fortament possible - - Tenir o obtenir les habilitats necessàries - - Comunicar els problemes que eviten trobar una solució efectiva + - Criticize without hostility + - Attend without resentment + - Work as hard as possible + - Behave or obtain the necessary skills + - Communicate the issues that prevent finding an effective solution -3. **Aprenentatge**: Tant si arribem al resultat desitjat com si no, aquest - procés haurà incrementat l'enteniment del projecte i les tecnologies - associades de totes les persones que hi participen. - En aquest procés una part crucial són les [Merge Request][mr] i les revisions - (**Reviews**) associades, així com la comunicació de l'equip que hi treballa. +3. **Learning**: Whether a desired result is reached or not, this process will help everyone involved, as it will increase the understanding of the project and its associated technologies. While working together [Merge Request][mr] and their associated reviews, as well as the communication between team working on and reporters are a crucial part. -Aplicant aquesta metodologia de manera iterativa anem millorant el projecte -incrementalment. +By applying this methodology in an iterative way, we improve the project incrementally. -Alguns recursos online gratuïts per familiaritzar-s'hi són: +Some free online resources to familiarize yourself with ASD are: - [https://users.exa.unicen.edu.ar/catedras/agilem/cap23asd.pdf](https://users.exa.unicen.edu.ar/catedras/agilem/cap23asd.pdf) - [https://www.geeksforgeeks.org/adaptive-software-development-asd/](https://www.geeksforgeeks.org/adaptive-software-development-asd/) From d551f46bbf893fbf5306e625f945a8bc47dd3d6f Mon Sep 17 00:00:00 2001 From: Aleix Quintana Alsius Date: Sun, 23 Apr 2023 14:20:45 +0000 Subject: [PATCH 07/18] WIP contributing translate --- docs/contributing.md | 69 +++++++++++++++++--------------------------- 1 file changed, 26 insertions(+), 43 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index 1058fef..3d02766 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -48,64 +48,47 @@ Some free online resources to familiarize yourself with ASD are: - [https://yewtu.be/watch?v=HXJWwxL2N5A](https://yewtu.be/watch?v=HXJWwxL2N5A) - [https://files.ifi.uzh.ch/rerg/amadeus/teaching/seminars/seminar_ws0304/06_Eberle_ASD_Folien.pdf](https://files.ifi.uzh.ch/rerg/amadeus/teaching/seminars/seminar_ws0304/06_Eberle_ASD_Folien.pdf) -### En la pràctica +### In practice -- Has detectat un problema? Ajuda'ns reportant un [problema/issue][issues]. -- Vols afegir un parche? Et pot ser útil l'apartat dels controls de qualitat - tot seguit. En funció de la complexitat dels teus canvis: +- Do you find any issue? Help us reporting the [issue][issues]. +- Do you want to add a patch? You'll find useful information in section quality control below. Depending on how complex are your changes: - - Si en són senzills, obre directament una [Merge Request][mr] - explicant el que vols afegir i per què. - D'aquesta manera iniciarà el procés de **revisió/review**. - - Si en són més complicats, potser posa't en contacte abans perquè puguem - avaluar si la teva solució és la que més s'adjusta al projecte. - Una bona manera de fer-ho és obrint una [issue][issues] explicant el que - vols fer, per què i com. + - Simple changes: Open a [Merge Request][mr] + explaining what are you adding and why. + Doing so a **review** process will be started. + - Complex changes: contact us before to decide if your solution is the optimal one for the project. + A good way of doing so is opening an [issue][issues] explaining what are you trying to to do, also why and how. -- Col·labores habitualment amb el DD? Ajuda amb les revisions de codi de les - [Merge Request][mr] pendents, tenint en compte els controls de qualitat. +- Do you often collaborate with DD? Help with the pending [Merge Request][mr] reviews, keeping in mind the quality control. [issues]: https://gitlab.com/DD-workspace/DD/-/issues [mr]: https://gitlab.com/DD-workspace/DD/-/merge_requests -## Controls de qualitat +## Quality controls ### Continuous Integration -Per simplificar la feina de revisió de codi i assegurar una certa qualitat del -que entra al repositori: +To simplify the review work and to ensure certain quality of what is integrated in repository: -- Ningú pot fer `push` a la branca principal (`main`) directament. - Sempre és necessari passar pel procés de [Merge Request][mr] i review. -- Disposem d'una instància de [buildbot][buildbot] com a Continuous Integration - (a `ci.dd-work.space`, login amb GitLab) que reacciona a esdeveniments de - tipus `push` al repositori principal, i de tipus [Merge Request][mr] des de - qualsevol repositori. - - Quan es tracta d'un [Merge Request][mr], només s'executen comprovacions - de estàtiques, que no executen el codi del repositori. - Això és per evitar abús de tipus mineria de criptomonedes i demés. - Aquestes comprovacions ara mateix són: - [ShellCheck][sc] per scripts de shell, [mkdocs][mkdocs] per comprovar - que la documentació es genera correctament, i aviat hi afegirem linters i - comprovadors estàndard de Python. - - Quan es tracta d'un esdeveniment `push` al repositori principal, - addicionalment a les comprovacions anteriors, es comença el procés - d'instal·lació des de zero en una màquina virtual. - Això ajuda a detectar quan s'introdueixen problemes i a assegurar que el - DD es pot instal·lar correctament. -- Els membres del grup `DD-workspace` a GitLab tenen permisos d'administració a - la instància de Buildbot, això els permet iniciar builds manualment o - cancel·lar tasques si és necessari. +- Nobody can direct `push` to `main` branch (`main`). + Always is necessary to follow the [Merge Request][mr] review proces. +- ** TO BE REVIEWED ( branch based events?? )** There is a [buildbot][buildbot] instance (in `ci.dd-work.space`, login via GitLab) as a Continuous Integration that reacts to `push` events in `main` branch and to [Merge Request][mr] events in any other branch. + - When the event is a [Merge Request][mr], only static checks are executed, so no complete tests are launched. + This is to prevent crypto mining CI/CD abuse. + These checks are the same as: + [ShellCheck][sc] for shell scripts, [mkdocs][mkdocs] to check that the documentation is generated as it should, soon we'll add linters and standard python checks. + - When the event is a `push` to `main`, + additionally to the [Merge Request][mr] tests, it will start the installation process from the scratch in a virtual machine. + This helps in detecting problems and makes sure that DD can be correctly. +- Members of group `DD-workspace` in Gitlab have administration permissions in Buildbot instance, this allow them to start or cancel build tasks manually if it is required. ### Checklist -Abans d'aprovar una Merge Request, hem de fer les següents comprovacions als -canvis que es volen introduir: +Before testing a Merge Request, we need to do these tests on the changes introduced: -- [ ] Passen les comprovacions a la CI -- [ ] Les modificacions introduïdes són necessàries, solucionen un problema - real, o milloren la mantenibilitat del projecte -- [ ] Es consideren i debaten les implicacions de **seguretat** +- [ ] CI Tests passing. +- [ ] The changes are needed, and solves a real problem. Also the changeset improves the maintenance of the project. +- [ ] ConsiderateEs consideren i debaten les implicacions de **seguretat** - [ ] Es consideren i debaten les implicacions de **mantenibilitat** - [ ] Es revisen possibles regressions de funcionalitat - [ ] No s'utilitzen dades reals en les proves From cd78248bffd01724391c9305d4db7a28720dac4a Mon Sep 17 00:00:00 2001 From: Aleix Quintana Alsius Date: Sun, 23 Apr 2023 16:05:42 +0000 Subject: [PATCH 08/18] Contributing translation --- docs/contributing.md | 64 +++++++++++++++++++++----------------------- 1 file changed, 30 insertions(+), 34 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index 3d02766..1d73758 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -4,7 +4,7 @@ DD is free software under AGPL3+ license, and contributions are welcome. ## Source code -The source code repository and techincal documentation is available at: +The source code repository and technical documentation is available at: [https://gitlab.com/DD-workspace/DD](https://gitlab.com/DD-workspace/DD) ## DD Architecture @@ -13,7 +13,7 @@ Code modifications will require you to familiarize yourself with DD architecture ![DD Workspace for education - Arquitectura](assets/diagram/dd_workspace_education.png) -**Note** This DD architecture diagram can be found in code respository in [editable][diagramedit] format. Like the rest of the whole code, you can suggest modifications +**Note** This DD architecture diagram can be found at code respository in [editable][diagramedit] format. Like the rest of the whole code, you can suggest modifications. [diagramedit]: https://gitlab.com/DD-workspace/DD/-/tree/main/docs/assets/diagram @@ -22,9 +22,9 @@ Code modifications will require you to familiarize yourself with DD architecture In order to organize contributions, adaptive software development methodology(ASD) is used. -This methodology focuses on self-organized team dynamics, interpersonal collaboration, and individual and team learning in a way that allows integrate the *Open Source* nature of **DD** with feedback or update cycles in the schools that are part of the pilot project and the technical needs of the project. +This methodology focuses on self-organized team dynamics, interpersonal collaboration, and individual and team learning in a way that allows integrating the *Open Source* nature of **DD** with feedback, technical needs and update cycles in the schools that are part of the pilot project. -ASD helps build complex software systems, in our case a digital educational environment. +ASD helps building complex software systems, in our case a digital educational environment. It is organized in iterative cycles of three phases : @@ -34,10 +34,10 @@ It is organized in iterative cycles of three phases : - Criticize without hostility - Attend without resentment - Work as hard as possible - - Behave or obtain the necessary skills + - Provide or obtain the necessary skills - Communicate the issues that prevent finding an effective solution -3. **Learning**: Whether a desired result is reached or not, this process will help everyone involved, as it will increase the understanding of the project and its associated technologies. While working together [Merge Request][mr] and their associated reviews, as well as the communication between team working on and reporters are a crucial part. +3. **Learning**: Whether a desired result is reached or not, this process will help everyone involved, as it will increase the understanding of the project and its associated technologies. While working together [Merge Request][mr] and their associated reviews, as well as the communication between work team and reporters are a crucial part. By applying this methodology in an iterative way, we improve the project incrementally. @@ -50,33 +50,32 @@ Some free online resources to familiarize yourself with ASD are: ### In practice -- Do you find any issue? Help us reporting the [issue][issues]. -- Do you want to add a patch? You'll find useful information in section quality control below. Depending on how complex are your changes: +- Did you find any issue? Help us reporting the [issue][issues]. +- Do you want to add a patch? You'll find useful information in quality control section below. Depending on how complex are your changes: - Simple changes: Open a [Merge Request][mr] explaining what are you adding and why. - Doing so a **review** process will be started. - - Complex changes: contact us before to decide if your solution is the optimal one for the project. - A good way of doing so is opening an [issue][issues] explaining what are you trying to to do, also why and how. + Doing so, a new **review** process will be started. + - Complex changes: Contact us before to decide if your solution is the optimal one for the project. + A good way of doing so, is opening an [issue][issues] explaining what are you trying to to do, also why and how you want to do. -- Do you often collaborate with DD? Help with the pending [Merge Request][mr] reviews, keeping in mind the quality control. +- Do you collaborate with DD often? Help us with the pending [Merge Request][mr] reviews, keeping in mind the quality control. [issues]: https://gitlab.com/DD-workspace/DD/-/issues [mr]: https://gitlab.com/DD-workspace/DD/-/merge_requests -## Quality controls +## Quality control ### Continuous Integration To simplify the review work and to ensure certain quality of what is integrated in repository: -- Nobody can direct `push` to `main` branch (`main`). +- Nobody can `push` commits directly to `main` branch (`main`). Always is necessary to follow the [Merge Request][mr] review proces. - ** TO BE REVIEWED ( branch based events?? )** There is a [buildbot][buildbot] instance (in `ci.dd-work.space`, login via GitLab) as a Continuous Integration that reacts to `push` events in `main` branch and to [Merge Request][mr] events in any other branch. - When the event is a [Merge Request][mr], only static checks are executed, so no complete tests are launched. This is to prevent crypto mining CI/CD abuse. - These checks are the same as: - [ShellCheck][sc] for shell scripts, [mkdocs][mkdocs] to check that the documentation is generated as it should, soon we'll add linters and standard python checks. + These checks are [ShellCheck][sc] for shell scripts, [mkdocs][mkdocs] to check that the documentation is generated as it should. Also, we will add soon linters and standard python checks. - When the event is a `push` to `main`, additionally to the [Merge Request][mr] tests, it will start the installation process from the scratch in a virtual machine. This helps in detecting problems and makes sure that DD can be correctly. @@ -84,27 +83,24 @@ To simplify the review work and to ensure certain quality of what is integrated ### Checklist -Before testing a Merge Request, we need to do these tests on the changes introduced: +Before integrating a Merge Request, we need to make sure that this checklist is passed: - [ ] CI Tests passing. -- [ ] The changes are needed, and solves a real problem. Also the changeset improves the maintenance of the project. -- [ ] ConsiderateEs consideren i debaten les implicacions de **seguretat** -- [ ] Es consideren i debaten les implicacions de **mantenibilitat** -- [ ] Es revisen possibles regressions de funcionalitat -- [ ] No s'utilitzen dades reals en les proves -- [ ] El resultat de la instal·lació des de zero en el CI és satisfactori - - [ ] És possible crear i modificar grups i usuaris - - [ ] És possible iniciar sessió amb SSO a Moodle, Nextcloud i Wordpress -- [ ] Es respecta el [Principi de mínima sorpresa (Principle Of Least Attonishment / POLA)][pola] - - [ ] Això inclou que es respectin les configuracions explícites - dels operadors (`dd.conf`) - - [ ] Les funcionalitats noves que puguin tenir efectes negatius, només - s'aplicaran per defecte, quan els operadors hagin tingut temps - suficient de desactivar-les abans +- [ ] The changes are needed, and solves a real problem. +- [ ] The changeset improves the maintenance of the project. +- [ ] **Security** implications are considerated and debated. +- [ ] **Manteinance** implications are considerated and debated. +- [ ] **Functional** regressions are reviewed. +- [ ] Tests are not done using real data. +- [ ] Succesful installation result from the scratch in CI. + - [ ] Is possible to create and update groups and users + - [ ] Is possible to start a sessions with SSO in Moodle, Nextcloud and Wordpress. +- [ ] Respect of [Principle Of Least Attonishment / POLA][pola] + - [ ] This includes respecting explicit configurations of operators(defined in `dd.conf`) + - [ ] The new features which may have negative effects, only will be applied by default when operators did have enough time to disable these before. -Si algun d'aquests passos falla, procedirem a ajudar a qui ha proposat els -canvis a solucionar els inconvenients. +If any of these steps fails, we'll try to help who requested the code merging to solve the problems. [buildbot]: https://buildbot.net -[pola]: https://en.wikipedia.org/wiki/Principle_of_least_astonishment +[pola]: https://en.wikipedia.org/wiki/Principle_of_least_astonishment \ No newline at end of file From b63cb092f972497de4e1e1f6615dcef2d5f4ed71 Mon Sep 17 00:00:00 2001 From: Aleix Quintana Alsius Date: Sun, 23 Apr 2023 17:06:55 +0000 Subject: [PATCH 09/18] Security translation --- docs/contributing.md | 2 +- docs/security.md | 69 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 70 insertions(+), 1 deletion(-) create mode 100644 docs/security.md diff --git a/docs/contributing.md b/docs/contributing.md index 1d73758..4ff20e2 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -100,7 +100,7 @@ Before integrating a Merge Request, we need to make sure that this checklist is - [ ] The new features which may have negative effects, only will be applied by default when operators did have enough time to disable these before. -If any of these steps fails, we'll try to help who requested the code merging to solve the problems. +If any of these steps fails, we'll try to help whoever has requested the code merge to solve the problems. [buildbot]: https://buildbot.net [pola]: https://en.wikipedia.org/wiki/Principle_of_least_astonishment \ No newline at end of file diff --git a/docs/security.md b/docs/security.md new file mode 100644 index 0000000..bcd985e --- /dev/null +++ b/docs/security.md @@ -0,0 +1,69 @@ +# Security + +## DD Configurations + +Currently the DD has the following specific options related to security: + +### Web Application Firewall (WAF) / Modsecurity + +Web Application Firewall/Modsecurity can be enabled following [these instructions](waf-modsecurity.md). + +### ClamAV / Antivirus + +As is done when enabling [WAF](waf-modsecurity.md), `ClamAV` can be enabled setting the variable `DISABLE_CLAMAV` to `true` in `dd.conf` and running: + +```sh +# Regenerate docker-compose.yml +./dd-ctl yml +# Start the container +./dd-ctl up +# Apply specific ClamAV configurations in other services +./dd-ctl personalize +``` + +## General system security + +System security can be complex, general criteria are set out here to help protect the system. + +Remember that you will have to apply your professional criteria to adapt following recommendations to your requirements. + + +### `dd.conf` file + +This is the main system configuration, **only the system administrators** must access it! Be sure that file permissions are set according to it. + +Review in new versions of DD the changes done in `dd.conf.sample` and set your `dd.conf` according to these changes. + +### Firewall + +As any exposed service in internet, is important to set correctly a firewall, DD only needs to be allowed the tcp ports 80/HTTP and 443/HTTPS. + +One option is using `ufw` with `deny` default incoming policy, and only allow 80 and 443 over TCP. + +Be careful to not disable access of ssh port if you are using it, as it will denies access to the system! +Read more about it in [SSH access](#acces-ssh). + +### SSH access + +Ideally, configure the firewall to deny access to all connections to port 22/SSH TCP. + +If you are not using a VPN, but you have any range of public ips, you can allow access to port 22/SSH to one of these public ips. + +If you are using a VPN, this is the best option. You'll need to configure in `/etc/ssh/sshd_config` the option `ListenAddress` to only allow the connection from the range of your VPN IP. Or set the firewall to only allow VPN IPs range. + +### SSH authentication + +**Never** use **password** when authenticating via ssh. + +Always use **asymmetric keys** and, if possible, a physical security device that keeps your private key in a secure way, something like [YubiKey](https://yubico.com). + +### Intrussion detection + +It is recommended to deploy `rkhunter` to detect system anomalies. +You can read configuration recommendations on this [wiki][serverstats]. + +## Other resources + +You can read more about security questions in this [public documentation][serverstats]. + +[serverstats]: https://gitlab.com/MaadiX/server-stats-and-check/-/wikis/en_home From 54bf31a066917576895a555af880b49d0de28728 Mon Sep 17 00:00:00 2001 From: Aleix Quintana Alsius Date: Sun, 23 Apr 2023 17:23:42 +0000 Subject: [PATCH 10/18] WAF translation --- docs/waf-modsecurity.md | 46 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 docs/waf-modsecurity.md diff --git a/docs/waf-modsecurity.md b/docs/waf-modsecurity.md new file mode 100644 index 0000000..e1dd384 --- /dev/null +++ b/docs/waf-modsecurity.md @@ -0,0 +1,46 @@ +# DD - Apache2 ModSecurity + HAProxy + +Installation of Apache2 ModSecurity and HAProxy. + +* In Apache2 with ModSecurity V3 enabled are included the OWASP rules. +* HAProxy service acts as application frontend and administers and negotiates the SSL domain certificate using Letsencrypt. +* Modsecurity is disabled by default when installing DD. +* The installation can be done with or without WAF part. +* If you have installed WAF you can set in bypass mode or enabled mode. + +## Apache - ModSecurity + +You can find the service definition in `dd-sso/docker/waf-modsecurity`. + +There are different files to set up this service: + +* `000-default.conf` contains Apache2 web service settings. +* `crs-setup.conf` is where is configured the OWASP ModSecurity Core Rule Set ver.3.2.0 . +* `modsec_rules.conf` contains the needed files for owasp service of Apache2. +* `rules_apps.conf` is where are configured the false positives, of different applications, that needs to be detected until the moment. + +### Enable/Disable + +DD can be used with WAF enabled or disabled, this is set in variable `DISABLE_WAF` in `dd.conf` file. + +The default value is `true` (WAF disabled), this will change in the future. + +``` +# Sample of dd.conf + +# Enable WAF +DISABLE_WAF=false + +# Disable WAF +DISABLE_WAF=true +``` + +### Configuration + +Changes in `dd.conf` are not immediate, you need to deploy again the DD containers using `dd-ctl`: + +```sh +./dd-ctl down +./dd-ctl build +./dd-ctl up +``` From eea3da38f812cc6718480bdd3e88ef72d43b394c Mon Sep 17 00:00:00 2001 From: Aleix Quintana Alsius Date: Sun, 23 Apr 2023 17:40:55 +0000 Subject: [PATCH 11/18] Extra docs translation --- docs/extra-docs.md | 159 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 159 insertions(+) create mode 100644 docs/extra-docs.md diff --git a/docs/extra-docs.md b/docs/extra-docs.md new file mode 100644 index 0000000..fd5c211 --- /dev/null +++ b/docs/extra-docs.md @@ -0,0 +1,159 @@ +# Extra documentation + +These configurations are automated, so are here only by informational purposes. + +## Keycloak configuration + +Go to `https://sso.DOMAIN/auth/admin/master/console` + +### THEMES + +- [ ] login theme: dd +- [ ] account theme: account-avatar +- [ ] internazionalization enabled: ON +- [ ] default locale: ca + + +1. Configure -> Realm Settings -> Themes + +Configure as this: + +![](img/snapshot/1FGGqna.png) + +### SECURITY DEFENSES + +- [ ] Change second line of Content-Security-Policy to: +`frame-src 'self'; frame-ancestors 'self' *.DOMAIN localhost; object-src 'none';` + +- [ ] Last one to: +`max-age=31536000; includeSubDomains` + +- [ ] Save + +![](img/snapshot/uS5uqJB.png) + +### CLIENT SCOPES + +- [ ] client scopes => mappers => role_list => Single Role Attribute: ON + +![](img/snapshot/Q2i349B.png) + +![](img/snapshot/KYbY4ao.png) + +![](img/snapshot/oJJPRdp.png) + +### CLIENT + +- [ ] Clients -> Account-console -> Settings -> Add a *Valid Redirect URIs* "https://moodle.DOMAIN.net/*" in addition to the wp one "https://wp.DOMINI.net/*" + +![](img/snapshot/vgamSuC.png) + +### EVENTS + +![](img/snapshot/events-keycloak.png) + + +### CLIENTS / account + +Add a valid redirection URI + +- [ ] `https://moodle.DOMAIN/*` +- [ ] `https://wp.DOMAIN/*` +- [ ] `/realms/master/account/*` +- [ ] `https://nextcloud.DOMAIN/*` + +![](img/snapshot/N_42e!m$3Fe.png) + +### Wordpress Configuration + +![](img/snapshot/Nk8YPCI.png) + +![](img/snapshot/3ZRPyzd.png) + +Configure the nickname of Wordpress: +![](img/snapshot/uOwYjOJ.png) + +Script: +``` +var Output = user.getFirstName()+" "+user.getLastName(); +Output; +``` + +#### To allow closing the SAML session from Wordpress + +![](img/snapshot/myofFZv.png) + +Add these settings: + +`/realms/master/account/*` +`https://wp.DOMAIN/*` + +![](img/snapshot/7U9t8Zn.png) + +Save the configuration. + +## Nextcloud configuration + +### Email +- To configure email: + +![](img/snapshot/5jIt2EE.png) +![](img/snapshot/gMQAKmb.png) + + +### Circles + +1. To download the Circles application: Applications -> Featured apps -> Circles (Download and enable) + +![](img/snapshot/yyNyUvc.png) + +2. A new menu entry will exist in Settings + +![](img/snapshot/IbRuJqC.png) + +3. Get back to Settings and click "Administration" >> "Groupware" configuration: + +![](img/snapshot/yjbOrLz.png) + +It could be enabled by command line: + +``` +docker exec -u www-data dd-apps-nextcloud-app php occ --no-warnings config:app:set circles members_limit --value="150" +docker exec -u www-data dd-apps-nextcloud-app php occ --no-warnings config:app:set circles allow_linked_groups --value="1" +docker exec -u www-data dd-apps-nextcloud-app php occ --no-warnings config:app:set circles skip_invitation_to_closed_circles --value="1 +``` + +### Other configurations + +4. Add docker network as whitelist. Administration -> Security +![](img/snapshot/9RxNQNx.png) + +5. Configure OnlyOffice templates in Nextcloud + +![](img/snapshot/ogGM_pzr3ybW.png) + +And save + +## Wordpress settings + +### SAML2 plugin + + +**1. Login as admin in WordPress (with closed session in other environments): https://wp.\/wp-login.php?normal** + +**2. Enable plugin "OneLogin SAML SSO" and apply changes** + + +### Generate Block plugin and GeneratePress theme + +Check that GenerateBlock plugin and GeneratePress theme are installed and enabled. + +![](img/snapshot/gZGNZXY.png) + +![](img/snapshot/iThTdIa.png) + +### Date and time + +- To set up date and time: + +![](img/snapshot/JbyHUqJ.png) From d423fedf39238bab91e4d08c417e4f29aaf3dc3f Mon Sep 17 00:00:00 2001 From: Aleix Quintana Alsius Date: Sun, 23 Apr 2023 17:54:38 +0000 Subject: [PATCH 12/18] Wildcard translation --- docs/wildcard.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 docs/wildcard.md diff --git a/docs/wildcard.md b/docs/wildcard.md new file mode 100644 index 0000000..d0955dc --- /dev/null +++ b/docs/wildcard.md @@ -0,0 +1,46 @@ +# Install of existing wildcard certificate + +First of all, stop the suite using: + +`/opt/src/DD# ./dd-ctl down` + +To make certificate compatible with DD, you need to merge the fullchain with the private key of the certificate, the best way of doing this is concatenating two files in a new one: + +`/tmp/certificatw# cat fullchain.pem cert.key > /opt/DD/src/haproxy/certs/chain.pem` + +The fullchain.pem file must contain all the certificate chain, cert.key is the private key, it needs to end up something like this: + +``` +> cat /opt/DD/src/haproxy/certs/chain.pem +-----BEGIN CERTIFICATE----- +YDC ... +... +... PnQP +-----END CERTIFICATE----- + +-----BEGIN CERTIFICATE----- +5dSf ... +... +... Hwgs +-----END CERTIFICATE----- + +-----BEGIN CERTIFICATE----- +sI3q ... +... +... vZas +-----END CERTIFICATE----- + +-----BEGIN RSA PRIVATE KEY----- +vzKJ ... +... +... 2dLs +-----END RSA PRIVATE KEY----- +``` + +Review the route where you created the new file chain.pem, it must be in /opt/DD/src/haproxy/certs + +Once this is done restart the suite: + +`/opt/src/DD# ./dd-ctl up` + +Domain certificate must work then. \ No newline at end of file From e32e83a2e8e79ac8d008fa12449a2cfd7b8b047f Mon Sep 17 00:00:00 2001 From: Aleix Quintana Alsius Date: Sun, 23 Apr 2023 18:12:29 +0000 Subject: [PATCH 13/18] Update install.md --- docs/install.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install.md b/docs/install.md index 2082708..e1d9880 100644 --- a/docs/install.md +++ b/docs/install.md @@ -21,7 +21,7 @@ Using the script [`dd-install.sh`][dd-install.sh] without any arguments will pro [dd-install.sh]: https://dd-work.space/docs/dd-install.sh -The wizard will guide you through the installation process. it will ask you a sequence of questions, to install and configure for the first time. +The wizard will guide you through the installation process. It will ask you a sequence of questions, to install and configure for the first time. Once installation is complete, you can proceed with the [post-installation](post-install.md). From 5b8fcdabde7afa2aff7d588a09c814d80987b614 Mon Sep 17 00:00:00 2001 From: Aleix Quintana Alsius Date: Sun, 23 Apr 2023 18:19:53 +0000 Subject: [PATCH 14/18] Update install.md --- docs/install.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/install.md b/docs/install.md index e1d9880..023f36f 100644 --- a/docs/install.md +++ b/docs/install.md @@ -84,13 +84,12 @@ You can use your own certificate, being it a single, wildcard or SAN certificate The installer accepts all the variables existing in [`dd.conf.sample`][dd.conf.sample] as environment variables using the `DD_` prefix to distinct of other environment variables. -For example, the variable `DOMAIN` can be pre-configured with the environment variable `DD_DOMAIN`. -Read the next example. +For example, the variable `DOMAIN` can be pre-configured with the environment variable `DD_DOMAIN`, as seen in the example below. If `DD_DOMAIN` is defined, the unattended installation will be started using values from environment variables. Otherwise, without defining `DD_DOMAIN`, it will proceed with the unattended installation. -Take note that when using the unattended mode, the dns records must resolve to your server ip address. You will need to setup DNS records for: +Take note that when using the unattended mode, the dns records must resolve to your server ip address. So, you will need to setup DNS records for: - moodle.${DD_DOMAIN} - nextcloud.${DD_DOMAIN} From 45b5d2fc76e217a60a0332b6f0c48c434c55982f Mon Sep 17 00:00:00 2001 From: Aleix Quintana Alsius Date: Sun, 23 Apr 2023 18:21:53 +0000 Subject: [PATCH 15/18] Update install.md --- docs/install.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install.md b/docs/install.md index 023f36f..6f9673f 100644 --- a/docs/install.md +++ b/docs/install.md @@ -143,6 +143,6 @@ The manual install is documented in file [`dd-install.sh`][repo-dd-install.sh] f # ``` -You will find comments for each step along with their respective commands. +You will find comments for each step, along with their respective commands. Once installation is complete, you can proceed with the [post-installation](post-install.md). From 9975f139ab90e15f2eb01b494440acb512381cb0 Mon Sep 17 00:00:00 2001 From: Aleix Quintana Alsius Date: Sun, 23 Apr 2023 18:25:16 +0000 Subject: [PATCH 16/18] Update file customising.md --- docs/customising.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/customising.md b/docs/customising.md index 57aff9b..93760bb 100644 --- a/docs/customising.md +++ b/docs/customising.md @@ -46,7 +46,7 @@ apps_internal: ``` -## Peu de pàgina en el login +## Login page Footer The footer is part of the Keycloak login theme, to modify it, it needs to use a theme based on 'dd' theme. @@ -55,7 +55,7 @@ To make things easier, in directory `dd-sso/docker/keycloak/themes` there are th - `dd-custom`: an empty directory, what is created here, keycloak will use as a new `dd-custom` theme. - `dd-custom.sample`: an example of how the theme `dd-custom` would be prepared in order to replace the footer. -So, to customize the footer, you need to copy the contents of `dd-custom.sample` to `dd-custom`, then edit `dd-custom/login/dd-footer.ftl` to suit our needs. +So, to customize the footer, you need to copy the contents of `dd-custom.sample` to `dd-custom`, then edit `dd-custom/login/dd-footer.ftl` to suit your needs. Once this is done, in the keycloak administration interface you need to pick `dd-custom` as a login theme: @@ -65,6 +65,6 @@ Once this is done, in the keycloak administration interface you need to pick `dd > to review the chnges with maintained `dd` theme, the contents of directory `dd-custom` > and contents of `dd-custom.sample` to make your customization compatible. -## Integració amb altres eines +## Integration with other tools It is possible to integrate DD with other tools, read about it in [integrations](integrations.md) section. \ No newline at end of file From e87d1188cf42f094dea3838fc6f235beb58f85f2 Mon Sep 17 00:00:00 2001 From: Aleix Quintana Alsius Date: Sun, 23 Apr 2023 18:44:45 +0000 Subject: [PATCH 17/18] troubleshooting translation --- docs/troubleshooting.md | 93 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 docs/troubleshooting.md diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 0000000..c95afa0 --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,93 @@ +# Troubleshooting + +## Software installation: + +To generate multiple domain and main domain certicates: +``` +apt install rsync vim tmux certbot -y +DOMAIN=digitaldemocratic.net +certbot certonly --preferred-challenges dns --manual --email digitaldemocratic@$DOMAIN --agree-tos -d *.$DOMAIN,$DOMAIN + +``` + +## Data and configuration removal + +If you want to start from the scratch you can remove data and code (optional) + +Esborrar dades: +``` +./dd-ctl reset-data + +``` + +Remove data, configuration, code and certificates: + +``` +cd /opt/DD/src +./dd-ctl reset-data +# Following commands RESET ALL DATA except for certificates +# execute them only if you know what you are doing +# This *will* result in DATA LOSS + "./dd-ctl" down + rm -rf /opt/DD/data/* + rm -rf /opt/DD/db/* + rm -rf '/opt/DD/src/avatars' + rm -rf '/opt/DD/src/moodle' + rm -rf '/opt/DD/src/nextcloud' + rm -rf '/opt/DD/src/wordpress' + +cd .. +rm -rf /opt/DD/src + +hostname=test1 +cp /opt/src/DD/dd.conf /opt/src/dd.conf.backup + +git clone https://gitlab.com/DD-workspace/DD /opt/src/DD +cd /opt/src/DD +cp dd.conf.sample dd.conf +cp -r custom.sample custom +./securize_conf.sh +# Change domain names in dd configuration to machine's hostname +sed -i "s/DOMAIN=mydomain.com/DOMAIN=$hostname.digitaldemocratic.net/g" dd.conf +sed -i "s/LETSENCRYPT_DNS=/LETSENCRYPT_DNS=$hostname.digitaldemocratic.net/g" dd.conf +sed -i "s/LETSENCRYPT_EMAIL=/LETSENCRYPT_EMAIL=info@digitaldemocratic.net/g" dd.conf + +./dd-ctl repo-update +``` + +### Problems with dns if automatic renewal is not working, dns challenge method + +```bash +docker exec -ti dd-sso-haproxy /bin/sh +``` + +In docker: + +```bash +mkdir /certs/selfsigned +mv /certs/*.pem /certs/selfsigned/ +cat /etc/letsencrypt/live/$DOMAIN/fullchain.pem /etc/letsencrypt/live/$DOMAIN/privkey.pem > /certs/chain.pem +exit +``` + +### Keycloak cache clean + +Run these command **step by step**: + +```bash +docker exec -ti dd-sso-keycloak /opt/jboss/keycloak/bin/jboss-cli.sh --connect --command='/subsystem=keycloak-server/theme=defaults/:write-attribute(name=cacheThemes,value=false)' + +docker exec -ti dd-sso-keycloak /opt/jboss/keycloak/bin/jboss-cli.sh --connect --command='/subsystem=keycloak-server/theme=defaults/:write-attribute(name=cacheTemplates,value=false)' + +docker exec -ti dd-sso-keycloak /opt/jboss/keycloak/bin/jboss-cli.sh --connect --command='/subsystem=keycloak-server/theme=defaults/:write-attribute(name=staticMaxAge,value=-1)' + +docker exec -ti dd-sso-keycloak /opt/jboss/keycloak/bin/jboss-cli.sh --connect --command='reload' + +docker exec -ti dd-sso-keycloak /opt/jboss/keycloak/bin/jboss-cli.sh --connect --command='/subsystem=keycloak-server/theme=defaults/:write-attribute(name=cacheThemes,value=true)' + +docker exec -ti dd-sso-keycloak /opt/jboss/keycloak/bin/jboss-cli.sh --connect --command='/subsystem=keycloak-server/theme=defaults/:write-attribute(name=cacheTemplates,value=true)' + +docker exec -ti dd-sso-keycloak /opt/jboss/keycloak/bin/jboss-cli.sh --connect --command='/subsystem=keycloak-server/theme=defaults/:write-attribute(name=staticMaxAge,value=2592000)' + +docker exec -ti dd-sso-keycloak /opt/jboss/keycloak/bin/jboss-cli.sh --connect --command='reload' +``` From 1eb8cc23a11bed30475b409919e4e6b6b5d3fefa Mon Sep 17 00:00:00 2001 From: Aleix Quintana Alsius Date: Sun, 23 Apr 2023 18:46:19 +0000 Subject: [PATCH 18/18] Update contributing.md --- docs/contributing.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index 4ff20e2..e4b9ec5 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -72,7 +72,7 @@ To simplify the review work and to ensure certain quality of what is integrated - Nobody can `push` commits directly to `main` branch (`main`). Always is necessary to follow the [Merge Request][mr] review proces. -- ** TO BE REVIEWED ( branch based events?? )** There is a [buildbot][buildbot] instance (in `ci.dd-work.space`, login via GitLab) as a Continuous Integration that reacts to `push` events in `main` branch and to [Merge Request][mr] events in any other branch. +- There is a [buildbot][buildbot] instance (in `ci.dd-work.space`, login via GitLab) as a Continuous Integration, that reacts to `push` events in `main` branch and to [Merge Request][mr] events in any other branch. - When the event is a [Merge Request][mr], only static checks are executed, so no complete tests are launched. This is to prevent crypto mining CI/CD abuse. These checks are [ShellCheck][sc] for shell scripts, [mkdocs][mkdocs] to check that the documentation is generated as it should. Also, we will add soon linters and standard python checks. @@ -103,4 +103,4 @@ Before integrating a Merge Request, we need to make sure that this checklist is If any of these steps fails, we'll try to help whoever has requested the code merge to solve the problems. [buildbot]: https://buildbot.net -[pola]: https://en.wikipedia.org/wiki/Principle_of_least_astonishment \ No newline at end of file +[pola]: https://en.wikipedia.org/wiki/Principle_of_least_astonishment