Quickstart

Get it running

Because of docker it is pretty easy to get everything up and running. To really develop conveniently locally you need to install some additional dependencies which are explained in start_devel_section.

For windows 10 machines

First open up the Power Shell and enable wsl and virtual machine features

# enable wsl
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

# enable virtual machine features
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Then let’s get the machine restarted. After the restart get back to the Power Shell again:

# update the linux kernel package
# see step 4 on https://docs.microsoft.com/en-us/windows/wsl/install-win10#step-4---download-the-linux-kernel-update-package

# set wsl version to 2
wsl --set-default-version 2

Then download linux distro from the microsoft store. Eg Ubuntu 20.04 LTS from https://www.microsoft.com/store/productId/9N6SVWS3RX71

And launch it, setup your linux user and password and you are ready to go.

Checkout your git project directly in the linux shell (not the powershell)

Note

All commands from now on (if not noted otherwise) should all be run inside the linux subsystem (WSL) shell in a bash compatible shell.

For better developer experience in the IDE which is usually run on windows directly, it is recommended to map a drive letter to the network share of wsl so. Eg map \\wsl$\Ubuntu\home\john to letter Z so that you can access your project from the IDE easily.

Note

There is an open bug for WSL https://github.com/microsoft/WSL/issues/4739 which (might) lead to a broken auto reloading functionality of changes to source files in development mode (local_dev). If you experience this eg. for angular reloading or bid reloading there are polling options (as a workaround). To activate them see the comments in * Angular Frontend: conf/docker/webapp/frontend/webapp/Dockerfile.dev * BI Daemon: conf/docker/webapp/server/bid/start_dev.sh

Requirements

In order to run your project accordingly some requirements must be met. On your machine you need to install:

Install docker and docker compose

To run docker you need to download docker for your platform. You can get the installation files at the following link: > https://docs.docker.com/install/

You also need to install Docker Compose. For Windows and Mac, docker compose is installed together with docker. For all other platforms you need to install it manually. You can find the instructions at the following link > https://docs.docker.com/compose/install/.

If you want to make sure, that docker is running open a console and type the following command:

docker info

You should get an output like:

 Debug Mode: false

Server:
 Containers: 7
  Running: 3
  Paused: 0
  Stopped: 4
 Images: 278
 Server Version: 19.03.8
 Storage Driver: overlay2
...

Configuring docker for windows

When you are using windows you need to configure docker. The following link will guide you through this process: > https://nickjanetakis.com/blog/a-linux-dev-environment-on-windows-with-wsl-2-docker-desktop-and-more

Configure environment

For local development set the current environment to local_dev

cli/env.sh local_dev

Generate local SSL Certs for development

TBD: why do we need this certificates? Explain this section a little bit more in detail

Generates local self signed ssl certificates which are located in conf/dev-certs, can be checked in.

cli/generate_local_dev_certs.sh

Add the hostnames for development

Add the local domains eg. (Replace domain example.com with your domain)

  • app.example.com.local

  • www.example.com.local

  • docs.example.com.local

  • cdn.example.com.local

to /etc/hosts like this.

127.0.0.1       localhost app.example.com.local www.example.com.local docs.example.com.local cdn.example.com.local
255.255.255.255 broadcasthost
::1             localhost

In Windows you need to set your hosts file in the Windows machine (this is copied in the Linux subsystem). Open power shell as administrator and edit following file: c:\windows\system32\drivers\etc\hosts.

Build System

In order to start your webapp you need to run the following commands:

cli/build_local_webapp.sh

The command build_loca_webapp.sh installs everything needed within the docker container. It’ll download everything automatically so make sure that you have internet access. This command takes around 10 minutes (TBD: measure time). ~

Start System

cli/start_webapp.sh

TBD: explain containers

The command start_webapp.sh starts all docker containers. The following containers will be started:

  • webapp-server-postgres-container

  • webapp-server-bid-container

  • webapp-server-proxy-container

  • webapp-server-redis-container

  • infra-server-ingress-nginx-container

  • webapp-frontend-webapp-container

  • webapp-docs-container

  • webapp-server-minio-container

For starting up some helper containers are also started but they are stopped immediately after everything is up and running:

  • example-project_webapp-server-minio-init-job_1

  • webapp-server-webapp-base-container

  • webapp-server-proxy-base-container

  • webapp-server-webapp-assets-builder-container

  • webapp-server-webapp-assets-builder-base-container

When all the containers are started everything can be reached (Replace domain example.com with your domain): - app.example.com.local -> the angular webapplication - www.example.com.local -> the wagtail website - docs.example.com.local -> the documentation

Don’t forget to trust the certificates, otherwise it won’t work.

Install Requirements for Development

In order to run your project accordingly some requirements must be met. On your machine you need to install:

If you are using an IDE like PyCharm, Webstorm, etc you have to install all dependencies locally as well in order to get the full IDE support and autocompletion.

Server installation

The following command will install all needed dependencies for server development.

./cli/install_dev_server_locally.sh

Frontend installation

To install the frontend dependencies you need to run the following commands. This will download all used packages so that you can use them within your IDE.

./cli/install_dev.sh
./cli/install_dev_frontend_webapp.sh

Install angular cli with the following command

npm install -g @angular/cli

Setup IDE (Pycharm)

  • Right click on Server/webapp > Mark Directory as ... > Source Root

  • Settings (Cmd + ;) > Project: cnc-base > Project Interpreter

  • Click on Project Interpreter dropdown > Show all > click + (bottom left)

  • On the left side menu click Virtualenv Environment > Existing environment > click ...

  • Browse to ... /demo-todo-app/Server/webapp/ENV/bin/python3.8

  • Click OK on all dialogs

  • Check if it is working

  • Done

Install dependencies for test system

Initialize database and create users

The following command will add testing data to the database. Make sure that all containers are started when you execute this command, because the data is stored in the docker containers.

cli/create_dev_db_testing_snapshots.sh

whenever you need to recreate the existing db snapshots eg. because you change testing data or change some models, do the following commands to recreate it from a fresh syste:

cli/stop_webapp.sh                           # stops all docker containers
cli/reset_dev_data.sh                 # delete all relevant volumes (eg. db volumes)
cli/start_webapp.sh                          # starts the containers who do some bootstrapping
cli/create_dev_db_testing_snapshots.sh       # creates the snapshot from the fresh running system

Setup test environment for webserver

The following command will install all libraries needed for testing the webserver

./cli/install_dev_server_tests_api.sh