Merge branch 'Docs-l10n' into 'Docs-l10n'
Docs l10n See merge request DD-workspace/DD!85merge-requests/85/merge
Aleix Quintana Alsius
commit
775865cff3
|
|
@ -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.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
**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
|
||||||
|
|
@ -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.
|
||||||
|
|
@ -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:
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
### 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
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
### CLIENT SCOPES
|
||||||
|
|
||||||
|
- [ ] client scopes => mappers => role_list => Single Role Attribute: ON
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
### CLIENT
|
||||||
|
|
||||||
|
- [ ] Clients -> Account-console -> Settings -> Add a *Valid Redirect URIs* "https://moodle.DOMAIN.net/*" in addition to the wp one "https://wp.DOMINI.net/*"
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
### EVENTS
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
### CLIENTS / account
|
||||||
|
|
||||||
|
Add a valid redirection URI
|
||||||
|
|
||||||
|
- [ ] `https://moodle.DOMAIN/*`
|
||||||
|
- [ ] `https://wp.DOMAIN/*`
|
||||||
|
- [ ] `/realms/master/account/*`
|
||||||
|
- [ ] `https://nextcloud.DOMAIN/*`
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
### Wordpress Configuration
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Configure the nickname of Wordpress:
|
||||||
|
|
||||||
|
|
||||||
|
Script:
|
||||||
|
```
|
||||||
|
var Output = user.getFirstName()+" "+user.getLastName();
|
||||||
|
Output;
|
||||||
|
```
|
||||||
|
|
||||||
|
#### To allow closing the SAML session from Wordpress
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Add these settings:
|
||||||
|
|
||||||
|
`/realms/master/account/*`
|
||||||
|
`https://wp.DOMAIN/*`
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Save the configuration.
|
||||||
|
|
||||||
|
## Nextcloud configuration
|
||||||
|
|
||||||
|
### Email
|
||||||
|
- To configure email:
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
### Circles
|
||||||
|
|
||||||
|
1. To download the Circles application: Applications -> Featured apps -> Circles (Download and enable)
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
2. A new menu entry will exist in Settings
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
3. Get back to Settings and click "Administration" >> "Groupware" configuration:
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
|
||||||
|
5. Configure OnlyOffice templates in Nextcloud
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
### Date and time
|
||||||
|
|
||||||
|
- To set up date and time:
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -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).
|
||||||
|
|
@ -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
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
!!swagger ddapi.json!!
|
||||||
|
|
@ -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:
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## 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
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
- 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
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
To test that it works, click on the next icon:
|
||||||
|
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Enable both options and save:
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
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
|
||||||
|
|
@ -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
|
||||||
|
|
@ -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'
|
||||||
|
```
|
||||||
|
|
@ -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
|
||||||
|
```
|
||||||
|
|
@ -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.
|
||||||
Loading…
Reference in New Issue