README.md

didmos2-demo-compose
============

# How to get started

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

## System requirements

### General requirements

For all functionality docker & docker-compose is required and must be installed manually:

- docker: [Official docs](https://docs.docker.com/compose/install/)
- docker-compose: [Official docs](https://docs.docker.com/compose/install/), version 1.25.0 or later

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

### 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)._


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

```
# +++ DOCKER CONFIGURATION +++
# ++++++++++++++++++++++++++++
# === DOCKER VARIABLES ===

...

SMTP_HOST=email.daasi.de
SMTP_USER=applications@daasi.de
SMTP_PASSWORD=secret

```

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.

### Step 2.c) Local development on core / frontend

_This scenario requires a bootstrapped environment for __full local development__ from either repository (internal or external) and in either version (develop or release)._

Setup mail credentials in didmos2-core/src/general/credentials.py

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


```
make bootstrap
```

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

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

By default the develop-branches of all repositories are used.

Use the flag ```ENV=release``` to setup with release-branches instead. The current release branches are specified in the file .env-build.

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

***

```
make pull
```

Pull most recent docker images from docker registry (gitlab.daasi.int). Usually these images are built with the Jenkins pipeline.

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

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

Stop all docker containers.

***

```
make up-frontend
```

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

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

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

***

```
make clean-fs
```

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

***

```
make clean-docker-all
```

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

***