diff --git a/README.md b/README.md index ade65a5..926b763 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,196 @@ # mindboost-infrastructure -All the software used and hosted by mindboost organized in containers. +All the software used and hosted by mindboost organized in containers. + +## 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}/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. + +Service Network Configuration: +- Frontend: Connected to proxy_network and backend_network +- Backend API: Connected to backend_network and database_network +- Database: Connected only to database_network +- Traefik: Connected only to proxy_network + +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. For example: + +```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 \ No newline at end of file