README.md 7.34 KB
Newer Older
David Huebner's avatar
David Huebner committed
1
didmos2-demo-compose
2 3
============

4 5
# How to get started

6 7 8 9 10 11 12
This respository contains all CI/CD related files for didmos2-demo. The main features are:

1) Local deployment using (prebuilt) docker images
2) Local development using a hybrid model with docker containers and locally run components
3) Jenkins pipeline for building & testing the software both as docker deployment and package deployment (currently Ubuntu 18)
4) Jenkins pipeline and manual instructions for setting up a production docker deployment

David Hübner's avatar
David Hübner committed
13
## System requirements
David Hübner's avatar
David Hübner committed
14

David Hübner's avatar
David Hübner committed
15
### General requirements
16

David Hübner's avatar
David Hübner committed
17
For all functionality docker & docker-compose is required and must be installed manually:
18 19

- docker: [Official docs](https://docs.docker.com/compose/install/)
David Hübner's avatar
David Hübner committed
20
- docker-compose: [Official docs](https://docs.docker.com/compose/install/), version 1.25.0 or later
21 22 23 24 25 26 27

Unless you are connected to DAASI's Internal network you need to add the following lines to your host file

```
127.0.0.1  auth.daasi.devel backend.daasi.devel frontend.daasi.devel
```

David Hübner's avatar
David Hübner committed
28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64
### Full local development environment requirements

For a full local development environment (i.e. when _not_ using `DEPLOY=dockerOnly`, see below), specific requirements must be fulfilled:

- Root permissions (sudo) on the local systems
- Fedora OS 29+

It's certainly possible to use another OS. However, this is untested and the steps done in scripts/bootstrap-devel.sh must be adopted manually.


## Step 1: Bootstrap environment

didmos2-demo contains of multiple components, which are developed in individual repositories. In order to start with development, a process called "bootstrap" must be run once. During this process, the source code of all components is cloned and various preparation is done. The environment can be bootstraped with either develop branches (the default) or the latest release versions. This can be controlled with the flag `ENV=release`, which is available for `make bootstrap`. When omitting this parameter, the default develop configuration is used.

Parts of these repositories (master and release tags) are published on the external gitlab. The develop branch is only published on the internal gitlab, hence all features, which refer to the develop branches are not applicable to use cases involving the external gitlab. For most commands this can be controlled with the flag `GIT_PROFILE=external`. When omitting this parameter, the default configuration with internal repositories is used.

Finally, the environment can be bootstraped either for a full local development environment (default) or only for docker containers. The first option allows development on frontend and backend using a development server, but has various specific requirements (see below). This can be controlled with the flag `DEPLOY=dockerOnly`. When omitting this parameter, a full bootstrap is performed.

In summary, the following bootstrap options may be interesting for different use cases:

`make bootstrap`: With access to daasi.int-repositories for development of frontend & backend

`make bootstrap DEPLOY=dockerOnly`: With access to daasi.int-repositories for docker-only development or deployment

`make bootstrap ENV=release GIT_PROFILE=external DEPLOY=dockerOnly`: Without access to daasi.int-repositories, where no develop branches exist and for docker-only development or deployment

## Step 2: Different development / deployment scenarios

After successfully bootstraping the environment (see Step 1), different scenarios can be used as follows:

### Step 2.a) Productive deployment

See README in the subdirectory deploy in this repository.

###  Step 2.b) Local deployment using docker containers (Quickstart)

_This scenario requires a bootstrapped environment (either full or dockerOnly) from either repository (internal or external) and in either version (develop or release)._
65

66 67 68

If you want to use functionalities which send email such as self-registration you need to change the variables in .env:

69
```
70 71 72
# +++ DOCKER CONFIGURATION +++
# ++++++++++++++++++++++++++++
# === DOCKER VARIABLES ===
73

74
...
75

76 77 78 79 80
SMTP_HOST=email.daasi.de
SMTP_USER=applications@daasi.de
SMTP_PASSWORD=secret

```
81 82 83 84 85 86 87 88 89 90

Finally execute:

```
make pull
make up
```

Open in Browser https://auth.daasi.devel and https://backend.daasi.devel and accept certificates. Next go to https://frontend.daasi.devel accept certificate again and you should be able to login as superadmin / secret.

David Hübner's avatar
David Hübner committed
91
### Step 2.c) Local development on core / frontend
92

David Hübner's avatar
David Hübner committed
93
_This scenario requires a bootstrapped environment for __full local development__ from either repository (internal or external) and in either version (develop or release)._
94

David Hübner's avatar
David Hübner committed
95
Setup mail credentials in didmos2-core/src/general/credentials.py
96 97 98 99 100 101 102 103

Now chose one of the make-up-* commands (see below for a complete list of Make-Commands). If you want to start both the frontend and backend locally, run:

```
make up-both-lib
```

# Full list of Make-Commands
104 105


David Huebner's avatar
David Huebner committed
106 107
```
make bootstrap
108
```
109

110
Setup development environment from a clean clone of the didmos2-demo-compose repository. Generally this should only be run once.
111

David Huebner's avatar
David Huebner committed
112
This checks out repositories for all components, runs setup for the local development environment (certificates etc.) and installs dependencies for local development (python, node, etc.)
David Huebner's avatar
David Huebner committed
113

David Huebner's avatar
David Huebner committed
114
By default the develop-branches of all repositories are used.
David Huebner's avatar
David Huebner committed
115

David Huebner's avatar
David Huebner committed
116 117
Use the flag ```ENV=release``` to setup with release-branches instead. The current release branches are specified in the file .env-build.

118
Use the flag ```DEPLOY=dockerOnly``` to only setup an environment to use docker containers. This does not allow local development on frontend / backend.
119

David Huebner's avatar
David Huebner committed
120 121 122 123
***

```
make pull
124
```
David Huebner's avatar
David Huebner committed
125

Benedikt Schnabel's avatar
Benedikt Schnabel committed
126
Pull most recent docker images from docker registry (gitlab.daasi.int). Usually these images are built with the Jenkins pipeline.
David Huebner's avatar
David Huebner committed
127 128 129 130 131 132 133 134 135

By default images tagged with __latest__ are pulled (this is specified in .env).

Use the flag ```ENV=release``` to use release images instead, which are specified in .env-dev-release.

***

```
make up
136
```
David Huebner's avatar
David Huebner committed
137 138 139 140 141 142 143 144 145 146 147 148

Start development environment with all components as docker containers.

By default images tagged with __latest__ are used (this is specified in .env).

Use the flag ```ENV=release``` to use release images instead, which are specified in .env-dev-release.


***

```
make down
149
```
David Huebner's avatar
David Huebner committed
150 151 152 153 154 155 156

Stop all docker containers.

***

```
make up-frontend
157
```
David Huebner's avatar
David Huebner committed
158 159 160 161 162 163 164 165 166 167 168

Start local frontend (non-docker) and other components as docker containers.

Use the flag ```ENV=release``` to use release images instead, which are specified in .env-dev-release.

Use the flag ```LIBDEV=true``` to allow frontend lib development. (There's also a shortcut: ```up-frontend-lib```)

***

```
make up-didmos
169
```
David Huebner's avatar
David Huebner committed
170 171 172 173 174 175 176 177 178 179 180

Start local backend (non-docker) and other components as docker containers.

Use the flag ```ENV=release``` to use release images instead, which are specified in .env-dev-release.

Use the flag ```NOSTART=true``` to allow manual start of backend server on port 8000.

***

```
make up-both
181
```
David Huebner's avatar
David Huebner committed
182 183 184 185 186 187 188 189 190 191 192 193

Start local frontend & backend (non-docker) and other components as docker containers.

Use the flag ```ENV=release``` to use release images instead, which are specified in .env-dev-release.

Use the flag ```NOSTART=true``` to allow manual start of backend server on port 8000.

Use the flag ```LIBDEV=true``` to allow frontend lib development. (There's also a shortcut: ```up-both-lib```)

***

```
David Hübner's avatar
David Hübner committed
194
make clean-fs
195
```
David Huebner's avatar
David Huebner committed
196 197 198 199 200 201 202

Remove all component repositories. Allows to re-run ```make bootstrap```.

***

```
make clean-docker-all
203
```
David Huebner's avatar
David Huebner committed
204 205 206 207

Remove  all (!) docker containers and didmos2-demo volumes.

***