diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000..e4b9ec5 --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,106 @@ +# Contribute + +DD is free software under AGPL3+ license, and contributions are welcome. + +## Source code + +The source code repository and technical documentation is available at: +[https://gitlab.com/DD-workspace/DD](https://gitlab.com/DD-workspace/DD) + +## DD Architecture + +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 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 + + +## Methodology: Adaptive software development(ASD) + +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 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 building complex software systems, in our case a digital educational environment. + +It is organized in iterative cycles of three phases : + +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: + + - Criticize without hostility + - Attend without resentment + - Work as hard as possible + - 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 work team and reporters are a crucial part. + +By applying this methodology in an iterative way, we improve the project incrementally. + +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/) +- [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) + +### In practice + +- 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 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 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 control + +### Continuous Integration + +To simplify the review work and to ensure certain quality of what is integrated in repository: + +- Nobody can `push` commits directly to `main` branch (`main`). + Always is necessary to follow the [Merge Request][mr] review proces. +- 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. + - 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 + +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. +- [ ] 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. + + +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 diff --git a/docs/customising.md b/docs/customising.md new file mode 100644 index 0000000..93760bb --- /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 + +``` + +## 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. + +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 your 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. + +## 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 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) diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 0000000..6f9673f --- /dev/null +++ b/docs/install.md @@ -0,0 +1,148 @@ +# 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`, 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. So, 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). 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!! 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 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 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' +``` 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 +``` 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