90 lines
4.0 KiB
Markdown
90 lines
4.0 KiB
Markdown
# 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 |