README.md 6 KB
Newer Older
benedikt.kroening's avatar
benedikt.kroening committed
1
2
3
# Open-Xchange App Suite Installer script collection

This collection contains several scripts for letting you install a fully fledged Open-Xchange environment.
benedikt.kroening's avatar
benedikt.kroening committed
4
By default this will install a singlenode environment consisting of:
benedikt.kroening's avatar
benedikt.kroening committed
5
6
    - Database (mysql or mariadb - take a look at the config file) 
    - Open-Xchange middleware (optionally with guard, documents(including dcs), documentconverter)
benedikt.kroening's avatar
benedikt.kroening committed
7
8
9
10
11
    - Apache2 Frontend

## Configuration

Basic Configuration is located inside the file `config/config`.
benedikt.kroening's avatar
benedikt.kroening committed
12
13
Most options can be overriden by using each shell-scripts parameters (sometimes described in the help text)

benedikt.kroening's avatar
benedikt.kroening committed
14
15
16
17
18
19
## Context configuration

You can configure the context that will be created later on by either modifying the existing qa env (`config/environment/qa`) or creating your own env folder (copy the qa folder and modify the two files accordingly).

In case of creating your own environment you have to manually call `config/environment/create-context.sh --environment <foobar>` since the qa context is currently hardcoded in case it is enabled in the config.

benedikt.kroening's avatar
benedikt.kroening committed
20
21
### Docker configuration

benedikt.kroening's avatar
benedikt.kroening committed
22
The docker configuration is located at `docker/config` and will override values from the above default config. 
benedikt.kroening's avatar
benedikt.kroening committed
23
You may also override config by providing environmental variables. 
benedikt.kroening's avatar
benedikt.kroening committed
24

benedikt.kroening's avatar
benedikt.kroening committed
25
26
27
28
29
30
31
32
33
34
35
36
37
There are some additional configuration variable used for docker-compose which are located at the repositories root (`.env`). These variables include:
 - `OX_VERSION` - This is used when building the images. Every built image will be tagged with this String (e.g. 7.10.3)
 - `OX_BASE_DISTRIBUTION` - The linux distribution to be used inside the docker images. Every used image is based on this (ox-base, this iamge gets tagged as well)
 - `OX_BASE_RELEASE` - The distributions release (e.g. Stretch or buster)
 - `OX_RUNTIME_DATA_PATH` - The location where docker-compose will store its data. This location is by default unter `docker/.runtime` but its recommended to put this outside of the git repo. 

The docker-compose environment is able to persist its data across restarts and recreations. Everytime a container gets recreated it fetches the required configuration from the consul. This includes databases IDs, oxguardpass and some flags used for determining the current clusters init state.
*IMPORTANT:* Recreating frontend or middleware nodes works without caution. For the database you have to ensure a gracefull shutdown (or enable the periodic database dump).
To shut it down properly execute: `docker-compose down -v`

 You can use consul to observe the init process when starting the environment. In addition to that you can use it to rudimentary monitor the services health.
 It is located at `http://localhost:8500`

benedikt.kroening's avatar
benedikt.kroening committed
38
39
40
41
42
## Versions

Versions can be configured at `setup/versions`
Check that file for more information.

43
44
### Database versions

benedikt.kroening's avatar
benedikt.kroening committed
45
46
47
48
49
50
By modifying the DATABASE_TYPE and DATBASE_VERSION variables (located in `config/config`) you can manually specify which database type and version to use. 
Currently supported are mysql and mariadb in all versions as listed on the support matrix in the oxpedia.

The installer will also take care of the required "ox-tunings" as described in the oxpedia (https://oxpedia.org/wiki/index.php?title=My.cnf). 
The file is currently located at `config/database/ox-tunings.cnf` and will simply be copied to the sql-servers configuration folder. 

51

benedikt.kroening's avatar
benedikt.kroening committed
52
53
54
55
56
57
58
59
60
61
## Good to know

This script collection has its roots in the old ox-quickinstall (or installer). Much of the install logic for the different distros was simply taken from there and still can be found at `lib/common.bash`

## How to use

Simple cli examples of how to use this

It is always a good idea to read documentation or help texts!

benedikt.kroening's avatar
benedikt.kroening committed
62
` $ ./ox-installer --help `
benedikt.kroening's avatar
benedikt.kroening committed
63

benedikt.kroening's avatar
benedikt.kroening committed
64
### Install singlenode with everything you need
benedikt.kroening's avatar
benedikt.kroening committed
65
66
67

Right now only frontend (apache), middleware and a database are installed.
It uses dovecot.qa.open-xchange.com as mail backend.
benedikt.kroening's avatar
benedikt.kroening committed
68
Please note that the '--singlenode' may be ommited as it is already set in 'config/config'
benedikt.kroening's avatar
benedikt.kroening committed
69

benedikt.kroening's avatar
benedikt.kroening committed
70
` $ ./ox-installer.sh --singlenode `
benedikt.kroening's avatar
benedikt.kroening committed
71
72
73

You can supply each component individually. Read the help text for more information.

benedikt.kroening's avatar
benedikt.kroening committed
74
75
### Add additiional features/components
Whenever you feel that you might want to test additional components you can install or enable them.
benedikt.kroening's avatar
benedikt.kroening committed
76
77
78
79
80
Take a look at the features/ direcotry for the feature related scripts. These scripts will install and configure the feature.

#### Guard
To enable / install guard on a node simply execute:

benedikt.kroening's avatar
benedikt.kroening committed
81
` $ features/guard.sh --install --singlenode --enable `
benedikt.kroening's avatar
benedikt.kroening committed
82

benedikt.kroening's avatar
benedikt.kroening committed
83
In an cluster environment you have to take care of the frontend and middleware node seperately. 
benedikt.kroening's avatar
benedikt.kroening committed
84
85
86
87
88
89
90

#### additional features
Take a look into the 'features' folder. You may enable/disable additional featues by executing those scripts.

This script is just an teamplate for later use, it does nothing, just sits there waiting to be copied to an actual feature...
` $ features/feature-template.sh --enable --restart `

benedikt.kroening's avatar
benedikt.kroening committed
91
92
93
94
95
96
## Docker

This installer supports creation of Open-Xchange docker images. These images will use supervisord as process monitor.
Right now it creates a simple groupware image (apache2, ox frontend, ox middleware). Seperate mail and database services are required.
Take a look at the docker-compose.yml at the root level of this repo.

benedikt.kroening's avatar
benedikt.kroening committed
97
### Build docker images
98
The installer script can be used as it is for docker environments. Take a look into the docker/ directory for some examples.
benedikt.kroening's avatar
benedikt.kroening committed
99
100
101
You can configure these environments by editing the `docker/config` file.

The images can be build by executing docker-composes build action:
benedikt.kroening's avatar
benedikt.kroening committed
102

benedikt.kroening's avatar
benedikt.kroening committed
103
`$ docker-compose build `
benedikt.kroening's avatar
benedikt.kroening committed
104

benedikt.kroening's avatar
benedikt.kroening committed
105
106
This will automatically install OX App Suite, Guard (documents with its several features will be added soon, this is wip).
The image will be tagged with the `OX_VERSION` tag (located at `.env`) on each rebuild...
107
108


benedikt.kroening's avatar
benedikt.kroening committed
109
110
### Start it

111
If you have docker-compose available you can use it to start the provided compose-environment, but make sure to be in the correct directory.
benedikt.kroening's avatar
benedikt.kroening committed
112
113
114

`$ docker-compose up`

benedikt.kroening's avatar
benedikt.kroening committed
115
Any runtime related files will be stored at `<repo>/docker/.runtime`
116

benedikt.kroening's avatar
benedikt.kroening committed
117
118
119
120
121
122
### Stop it

`$ docker-compose down -v`

### Clean it up

benedikt.kroening's avatar
benedikt.kroening committed
123
`$ rm -fr docker/.runtime/`