dev-env/README.md

AuA24 dev-env

Introduction

This project is the development environment of the AuA24 Dashboard.
It's purpose is to simplify the handling, maintenance and development of docker-enabled applications (systems).

Installation

• Create a .systems file bases on .systems.example: cp .systems.example .systems
• Enter all systems in the created file nano .systems
• Run ./init
• Perform initial actions on systems.
  This might include...
  • changing variables in your .env files, adjusting the docker/docker-compose.yml if necessary
  • adding file(s) to the system (e.g. the weblate.token)
• ./up to start your containers
  • up will also run all the bin/script/firstRun scripts, if the .firstRun marker is missing

Usage

After the installation was performed successfully and you've sourced your ~/.profile file, you'll have access to the following utilities

Binaries

denv

Syntax: denv [script]

• Without a passed script, navigates to the development environment.
• If script is passed, denv will try to execute the specified script in the dev-env base folder.

drun

Syntax: drun [system-identifier] <command>

• Executes a command on the 'app'-container of a system. (e.g. backend-app for backend)
• If a system-identifier is passed, the specified command will be executed on the 'app'-container for the passed system-identifier.
• If no system-identifier is passed, drun will try to identify the system by the folder you're currently in.

dcom

Syntax: dcom [system-identifier] <command>

• Executes a docker compose command for a specific system
• If a system-identifier is passed, the command will be for the docker/docker-compose.yml file of the passed system-identifier.
• If no system-identifier is passed, dcom will try to identify the system by the folder you're currently in.

Scripts

All these scripts are available in the dev-env base directory.
They may be called by either just executing them in the command line when you're in the dev-env base directory ./script or by using the denv binary from any place: denv script

build

Builds the images, which are used to start up docker containers

• Executes docker compose build for the dev-env
• Then executes dcom <system> build for each system

down

Stops all running containers and removes them afterwards.
This may lead to loss of data.

• Executes docker compose down for the dev-env
• Then executes dcom <system> down for each system

info

Displays information about the dev-env

• Full path to the environment
• An overview over all installed systems...
  • Identifier
  • Path relative to the dev-env
  • Currently checked out branch
  • An indicator whether there are uncommitted changes on the branch

init

Initializes the development environment.
It should skip unnecessary steps, in case the dev-env is already initialized.

• Creates certificates used by traefik to enable TLS (HTTPS)
• Creates access keys ~/.ssh/personal_bitbucket_access_key and ~/.ssh/bitbucket_access_key used for connecting a container with git
• Updates .aliases file, which enables you to switch between your systems easily via goto-<system-identifier>
• Updates .profile to use the updated aliases, enables the dev-env binaries (denv, drun, dcom, ...) and add some utility functions
• Clones all systems defined in .systems
• Calls the ./bin/script/init script for each cloned system

prune

Removes all containers and images from docker. This also includes all data saved on databases.
After confirmation...

• Stops all running docker containers
• Remove all containers and images

stop

Stops all running containers.

• Executes docker compose stop for the dev-env
• Then executes dcom <system> stop for each system

up

Starts all running containers.

• Executes docker compose up -d for the dev-env
• Then executes dcom <system> up -d for each system

update

Calls the bin/script/update script for each system