mindboost-infrastructure/README.md

# mindboost-infrastructure

All the software used and hosted by mindboost organized in containers.

## New Infra (v2) Overview

This repo now includes a modular, best‑practice infrastructure under `infra/` to make replication and selective deployment easy. It is centered on Traefik as the reverse proxy with automatic TLS via Let's Encrypt, environment layering, and pick‑what‑you‑need application stacks.

- Core: `infra/core/traefik` — Traefik with HTTPS (ACME), dashboard, and sane defaults
- Apps: `infra/apps/<service>` — self‑contained stacks (e.g., `nextcloud`)
- Env: `infra/env/<environment>/common.env` — environment defaults (dev/prod)
- Secrets: `infra/secrets/` — local secret storage (ignored by git)
- Make targets: top‑level `Makefile` to bootstrap, start proxy, and start apps

Quickstart

- Copy `infra/env/development/common.env` and adjust domains and ACME email.
- Create the shared proxy network and ACME storage: `make bootstrap`
- Start Traefik: `make proxy-up`
- Start a service, e.g. Nextcloud: `make app-up APP=nextcloud`

Notes

- Traefik dashboard is exposed at `TRAEFIK_DASHBOARD_DOMAIN` with optional basic auth.
- Services connect to an external `proxy` network for routing, plus their own internal network.
- Each app has its own `.env.example`; copy to `.env` and adjust.
- The legacy `apps/` structure remains as-is; new infra is additive and can coexist.

## Project Structure

./apps/
├── docker-compose.all.yml  # Orchestriert alle Docker Compose Stacks
│
├── frontend/
│   ├── docker-compose.yml
│   └── src/                 # Vue.js frontend source code
│
├── backend/
│   ├── docker-compose.yml
│   └── src/                 # Laravel backend source code
│
├── database/
│   └── docker-compose.yml   # MariaDB stack
│
├── website/
│   └── docker-compose.yml   # KirbyCMS public site stack
│
├── administration/
│   └── docker-compose.yml   # Portainer stack
│
├── proxy/
│   └── docker-compose.yml   # Traefik, Crowdsec, and Bouncer stack
│
├── develop/
│   └── docker-compose.yml   # Gitea, Jenkins, and Adminer stack
│
└── tools/
    └── docker-compose.yml   # Nextcloud, LimeSurvey, and LinkStack stack

## Current Services

1. Frontend (Vue.js)
2. Backend (Laravel)
3. Database (MariaDB)
4. Proxy (Traefik, Crowdsec, Bouncer)

## Upcoming Services

1. Website (KirbyCMS)
2. Administration (Portainer)
3. Development Tools (Gitea, Jenkins, Adminer)
4. Utility Tools (Nextcloud, LimeSurvey, LinkStack)

## Service Descriptions

### Current Services

- **Frontend**: Vue.js based user interface for the mindboost application.
- **Backend**: Laravel based API and server-side logic for the mindboost application.
- **Database**: MariaDB for data storage and management.
- **Proxy**: Traefik for reverse proxy, Crowdsec and Bouncer for security.

### Upcoming Services

- **Website**: KirbyCMS for the public-facing website.
- **Administration**: Portainer for container management and monitoring.
- **Development Tools**:
  - Gitea: Self-hosted Git service
  - Jenkins: Continuous Integration/Continuous Deployment (CI/CD) tool
  - Adminer: Database management tool
- **Utility Tools**:
  - Nextcloud: File hosting and collaboration platform
  - LimeSurvey: Online survey tool
  - LinkStack: Link management tool

## Deployment

Each service or group of related services has its own `docker-compose.yml` file in its respective folder under `./apps/`. This structure allows for modular deployment and easier management of individual services.

To deploy a service, navigate to its directory and run:

```bash
docker-compose up -d
```

For the entire infrastructure, a root `docker-compose.yml` file can be created to orchestrate all services together.

## Environment Configuration

Environment variables are managed in a centralized `env` folder at the root of the project. This structure allows for easy management of different environments and services.

./env/
│
├── development/
│   ├── frontend.env
│   ├── backend.env
│   ├── database.env
│   └── ...
│
├── staging/
│   ├── frontend.env
│   ├── backend.env
│   ├── database.env
│   └── ...
│
└── production/
    ├── frontend.env
    ├── backend.env
    ├── database.env
    └── ...

Each service's `docker-compose.yml` file references the appropriate `.env` file based on the current environment. For example:

```yaml
services:
  backend:
    env_file:
      - ../../env/${ENVIRONMENT:-development}/backend.env
```

## Networking

Our infrastructure uses a two-tier network model to enhance security and isolate services:

1. Proxy Network (proxy_network):
   - Exposed to the internet and contains the Traefik reverse proxy.
   - Only services that need to be publicly accessible should be connected to this network.
   - Example services: Traefik, frontend application.

2. Internal Networks:
   - Separate internal networks are created for each public service that needs to communicate with internal services.
   - These networks are not directly accessible from the internet and provide secure communication between public and internal services.
   - Examples: backend_network, database_network, etc.

This structure ensures that:
- The proxy (Traefik) can route traffic to public-facing services.
- Internal services (like databases) are not directly accessible from the proxy network.
- Each connection between a public and an internal service has its own isolated network.

This configuration minimizes the attack surface by isolating networks and ensuring that services only have access to the networks they absolutely need. Each connection between a public and an internal service is protected by a dedicated internal network, further enhancing security.

## Volumes

Persistent data should be managed using named volumes or bind mounts, depending on the requirements of each service. This ensures data persistence across container restarts and updates.

The `volumes/` folder contains subdirectories for different volumes used by various applications in the infrastructure. This centralized structure allows for easier management and backup of persistent data.

./volumes/
│
├── backend/                # Volume for backend-specific data
├── database/               # Volume for MariaDB data
├── website/                # Volume for KirbyCMS data
├── administration/         # Volume for Portainer data
├── develop/
│   ├── gitea/              # Volume for Gitea repositories and data
│   └── jenkins/            # Volume for Jenkins data and job configurations
└── tools/
    ├── nextcloud/          # Volume for Nextcloud files and data
    ├── limesurvey/         # Volume for LimeSurvey data
    └── linkstack/          # Volume for LinkStack data

Each subdirectory corresponds to a specific service or group of services, containing the persistent data that needs to be preserved across container restarts or redeployments. 

When configuring Docker Compose files, reference these volume paths to ensure data persistence.

```yaml
volumes:
  - ./volumes/database:/var/lib/mysql
```

## Scripts

The `scripts/` folder contains a collection of utility scripts for deployment, backup, and maintenance tasks. These scripts are designed to automate common operations and ensure consistency across different environments.

./scripts/
│
├── deployment/
│   ├── deploy-app.sh        # Script for deploying the main application
│   └── deploy-traefik.sh    # Script for deploying Traefik
│
├── backup/
│   ├── backup-database.sh   # Script for backing up the database
│   └── backup-files.sh      # Script for backing up file storage
│
└── maintenance/
    ├── update-services.sh   # Script for updating all services
    └── health-check.sh      # Script for performing health checks on services

These scripts can be run from the command line to perform various tasks related to the infrastructure. Always review and test scripts in a safe environment before using them in production.

To use a script, navigate to the scripts directory and run:

```bash
./script-name.sh