From ff46002a895a2cc8f0e637b7cce925302b7902da Mon Sep 17 00:00:00 2001 From: Aleix Quintana Alsius Date: Tue, 18 Apr 2023 13:55:51 +0000 Subject: [PATCH] Translate install.sh --- docs/install.md | 149 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 docs/install.md diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 0000000..2082708 --- /dev/null +++ b/docs/install.md @@ -0,0 +1,149 @@ +# Installation + +## Requirements + +GNU/Linux [debian](https://debian.org) based distribution able to run docker-compose v1.28 or newer. + +## Configuration + +It's a good idea to familiarize with the settings available in [`dd.conf.sample`][dd.conf.sample], which is the main configuration file. + +[dd.conf.sample]: https://gitlab.com/DD-workspace/DD/-/blob/main/dd.conf.sample + +The installation process must be done using `dd-install.sh`, answering the questions and/or passing environment variables, it will write a dd.conf based on the dd.conf.sample. As example: + +``` +> DD_NETWORK_MTU=1450 ./dd-install.sh +``` +## Guided install + +Using the script [`dd-install.sh`][dd-install.sh] without any arguments will proceed with the guided installation. + +[dd-install.sh]: https://dd-work.space/docs/dd-install.sh + +The wizard will guide you through the installation process. it will ask you a sequence of questions, to install and configure for the first time. + +Once installation is complete, you can proceed with the [post-installation](post-install.md). + +### Guided example + +```bash +# We obtain dd-install.sh +> wget https://dd-work.space/docs/dd-install.sh -O dd-install.sh +# Make it executable +> chmod +x dd-install.sh +# And run it +> ./dd-install.sh +Interactive install detected! +Please follow the instructions carefully: + +Under which DOMAIN will you install DD? example.org + + +You will need to setup DNS entries for: +- [ ] moodle.dd.004.es +- [ ] nextcloud.dd.004.es +- [ ] wp.dd.004.es +- [ ] oof.dd.004.es +- [ ] sso.dd.004.es +- [ ] pad.dd.004.es +- [ ] admin.dd.004.es +- [ ] api.dd.004.es +- [ ] correu.dd.004.es + + +What is the short title of the DD instance? [DD] +What is the full title of the DD instance? [DD] DD at example.org +Do you want to use Let's Encrypt certificates? [Y/n] Y +Which email will you use for Let's Encrypt notifications? letsencrypt@example.org +Generate a certificate for example.org? (neds the DNS entry) [y/N] N +Path to the logo's PNG file (optional): +Path to the background's PNG file (optional): +About to install with following information: + +DOMAIN=example.org +TITLE_SHORT=DD +TITLE=DD at example.org +LETSENCRYPT_DNS=example.org +LETSENCRYPT_EMAIL=letsencrypt@example.org +LETSENCRYPT_DOMAIN_ROOT=false + +Custom logo in PNG (if requested): +Custom background in PNG (if requested): +Is this correct? proceed with the install? [Y/n] Y +``` +
Logos +Optionally you can define the logos by placing the .png files on the server and indicate their path when the installer requests them. +
+ +
Pre-existing certificate +You can use your own certificate, being it a single, wildcard or SAN certificate. You can read more in the [wildcard](wildcard.md) section. +
+ +## Unattended install + +The installer accepts all the variables existing in [`dd.conf.sample`][dd.conf.sample] as environment variables using the `DD_` prefix to distinct of other environment variables. + +For example, the variable `DOMAIN` can be pre-configured with the environment variable `DD_DOMAIN`. +Read the next example. + +If `DD_DOMAIN` is defined, the unattended installation will be started using values from environment variables. +Otherwise, without defining `DD_DOMAIN`, it will proceed with the unattended installation. + +Take note that when using the unattended mode, the dns records must resolve to your server ip address. You will need to setup DNS records for: + + - moodle.${DD_DOMAIN} + - nextcloud.${DD_DOMAIN} + - wp.${DD_DOMAIN} + - oof.${DD_DOMAIN} + - sso.${DD_DOMAIN} + - pad.${DD_DOMAIN} + - admin.${DD_DOMAIN} + - api.${DD_DOMAIN} + +> It is worth noting that this way of installation can be automated with provisioning tools such as [Ansible][ansible], [cdist][cdist] or [Puppet][puppet]. + +[ansible]: https://ansible.com +[cdist]: https://cdi.st +[puppet]: https://puppet.com + +Once installation is complete, you can proceed with the [post-installation](post-install.md). + +### Unattended example + +```bash +> export DD_DOMAIN="example.org" +> export DD_TITLE="DD at example.org" +> export DD_TITLE_SHORT="DD" +> export DD_LETSENCRYPT_DNS="example.org" +> export DD_LETSENCRYPT_EMAIL="letsencrypt@example.org" +# +# +# We obtain dd-install.sh +> wget https://dd-work.space/docs/dd-install.sh -O dd-install.sh +# Make it executable +> chmod +x dd-install.sh +# And run it +> ./dd-install.sh +``` + +
Logos +Optionally you can define the logos by placing the .png files on the server and pointing the environment variables DDIMG_LOGO_PNG and +DDIMG_BACKGROUND_PNG to their path. +
+ +## Manual install + +The manual install is documented in file [`dd-install.sh`][repo-dd-install.sh] from line : + +[repo-dd-install.sh]: https://gitlab.com/DD-workspace/DD/-/blob/main/dd-install.sh + +```bash +# +# START MANUAL INSTALL +# +``` + +You will find comments for each step along with their respective commands. + +Once installation is complete, you can proceed with the [post-installation](post-install.md).