EDUCATIC
/
digitaldemocratic
mirror of https://gitlab.com/digitaldemocratic/digitaldemocratic
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge branch 'Docs-l10n' into 'Docs-l10n' 

Docs l10n

See merge request DD-workspace/DD!85
merge-requests/85/merge
Aleix Quintana Alsius 2023-04-23 18:55:27 +00:00
parent bf3f9178f7 1eb8cc23a1
commit 775865cff3
10 changed files with 900 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

106
docs/contributing.md Normal file
View File

@ -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

70
docs/customising.md Normal file
View File

@ -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.

159
docs/extra-docs.md Normal file
View File

@ -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.\<domain\>/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)

148
docs/install.md Normal file
View File

@ -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
```
<details><summary>Logos</summary>
Optionally you can define the logos by placing the <code>.png</code> files on the server and indicate their path when the installer requests them.
</details>
<details><summary>Pre-existing certificate</summary>
You can use your own certificate, being it a single, wildcard or SAN certificate. You can read more in the [wildcard](wildcard.md) section.
</details>
## 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
```
<details><summary>Logos</summary>
Optionally you can define the logos by placing the <code>.png</code> files on the server and pointing the environment variables <code>DDIMG_LOGO_PNG</code> and
<code>DDIMG_BACKGROUND_PNG</code> to their path.
</details>
## 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).

63
docs/integrations.md Normal file
View File

@ -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.
<details>
<summary>Read details</summary>
```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 <code>JWT</code> can be generated, e.g. using <code>python-jose</code>:
```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.
</details>
[jwt]: https://jwt.io/
[jose]: https://python-jose.readthedocs.io/
## API Notable
![Projecte NotaBLE](assets/images/notable.jpg)
!!swagger ddapi.json!!

100
docs/post-install.md Normal file
View File

@ -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

69
docs/security.md Normal file
View File

@ -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

93
docs/troubleshooting.md Normal file
View File

@ -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'
```

46
docs/waf-modsecurity.md Normal file
View File

@ -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
```

46
docs/wildcard.md Normal file
View File

@ -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.