This directory (`pyinfra/`) contains the automated infrastructure-as-code (IaC) deployment framework for the ETSI MEC Sandbox. It utilizes a declarative, Python-based deployment model using [Pyinfra](https://pyinfra.com/).
This guide walks you through deploying the **ETSI MEC Sandbox** using our automated, Python-based infrastructure-as-code ([PyInfra](https://pyinfra.com/)) framework.
## What it does
The framework automates the entire provisioning lifecycle—including kernel tuning, Docker/Containerd runtime installation, Kubernetes (`kubeadm`) cluster initialization, development tools (Go, Node.js, NVM), and compiling and running the MEC Sandbox microservices (`meepctl`).
This framework handles the end-to-end provisioning and configuration of the MEC Sandbox environment. Its core responsibilities include:
---
-**System Initialization:** Ensuring proper kernel modules, network routing, and core system dependencies are configured.
-**Container Runtimes:** Idempotent installation and configuration of Docker and Containerd.
-**Kubernetes Cluster Setup:** Bootstrapping the Kubernetes control plane and joining worker nodes via `kubeadm`.
-**Development Environment:** Installing specific versions of Golang, Node.js (via NVM), and linting tools.
-**Platform Orchestration (meepctl):** Configuring and deploying the MEC core platform, frontend, and dependencies using `meepctl`.
## Prerequisites
Everything in this folder is designed to be **idempotent**—you can safely run the deployment multiple times without causing unintended side effects or breaking the system.
Before deploying, ensure your target machine(s) meet the following requirements:
-**Python:** Python 3.8+ installed on the machine running this deployment.
-**Privileges:** Sudo (root) access on the target deployment machines.
-**Network:** Outbound internet access to download required containers, packages, and binaries.
---
## How to Run the Deployment
Follow these steps to deploy the infrastructure.
### 1. Initial Setup
## Quick Start (3 Steps)
Before deploying, you must initialize your local environment. We provide an automated bootstrap script that ensures Python 3 is installed, sets up an isolated virtual environment (`pyinfra-venv`), and installs the `pyinfra` package cleanly.
### Step 1: Initialize the Deployment Environment
Run the automated setup script to verify Python 3, create an isolated virtual environment (`pyinfra-venv`), and install all required deployment dependencies:
```bash
cd pyinfra
./setup.sh
```
### 2. Configure Environment Variables
### Step 2: Configure Your Environment (`.env`)
The first time you run `./setup.sh`, it generates a `.env` configuration file from `.env.example` and pauses so you can enter your settings.
Open `.env` in your text editor and configure the following required fields:
-**`K8S_MASTERS`:** Mandatory target host for the Kubernetes control plane (exactly 1 master node is supported; e.g., `localhost` for local deployments, or `ubuntu@192.168.1.10` for remote servers).
-**`K8S_WORKERS`:** Optional comma-separated list of worker node IPs/hostnames. Leave blank (`""`) for single-machine deployments.
-**`MEC_HOST_ADDRESS`:** The routable IP address or domain name where the MEC Sandbox frontend will be accessible (e.g., `127.0.0.1`, `192.168.1.100`, or `mec.example.com`).
-**OAuth Provider Credentials:** Provide valid OAuth secrets for **GitHub** (`GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`), **GitLab**, or both. Unconfigured providers are automatically disabled in the platform configuration.
> [!IMPORTANT]
> **Do not set both `K8S_MASTERS` and `K8S_WORKERS` to `localhost`.**
> A single machine cannot act as both an independent Kubernetes master and worker node. For an all-in-one sandbox on your local machine, set `K8S_MASTERS="localhost"` and leave `K8S_WORKERS=""`.
If this is your first time running the setup script, it will automatically generate a `.env` file from the `.env.example` template and exit safely to allow you to configure your secrets.
### Step 3: Run the Deployment
Activate the virtual environment and launch the deployment:
Open the `.env` file in your preferred editor and configure the necessary variables:
-**MEC_HOST_ADDRESS:** Set the routable IP or domain for the MEC frontend.
-**OAuth Secrets:** Configure your **GitHub** OAuth credentials (`GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`), **GitLab** OAuth credentials (`GITLAB_CLIENT_ID`, `GITLAB_CLIENT_SECRET`), or **both**.
-*Best Practice Check:* At least one OAuth provider (GitHub or GitLab) must be configured with a valid Client ID and Secret. Unconfigured providers are automatically disabled in `.meepctl-repocfg.yaml`, and configured providers are enabled and updated idempotently.
```bash
source pyinfra-venv/bin/activate
pyinfra inventory.py deploy.py
```
---
### 3. Deploying the Infrastructure
## Authentication & Sudo Passwords
Once the `.env` file is properly configured, activate the virtual environment and execute the Pyinfra deployment.
For security, **sudo passwords are never stored in config files or environment variables.**
The deployment process slightly differs depending on whether you are deploying locally or to remote servers.
When you launch `pyinfra inventory.py deploy.py`:
1.**Prompted Once at Startup:** PyInfra will prompt you in the terminal for your sudo password:
```text
Enter sudo password for K8S_MASTERS node(s) (press Enter for passwordless sudo):
```
2.**Worker Credentials (If Applicable):** If you configured remote `K8S_WORKERS`, you will be prompted separately for the worker nodes' sudo password.
3.**Non-Interactive Execution:** After entering your password at startup, PyInfra caches it in memory and automatically authenticates all sudo operations in the background. You will not be prompted again during the deployment.
#### Option A: Local Deployment (Localhost)
If you are deploying the sandbox directly to the machine you are currently logged into:
---
1. Ensure `K8S_MASTERS="localhost"` in your `.env` file.
2. Run the deployment:
## Deployment Modes
### Option A: Local / Single-Machine Deployment (Default)
To deploy the entire MEC Sandbox directly on the machine you are currently logged into:
1. Set `K8S_MASTERS="localhost"` and `K8S_WORKERS=""` in `.env`.
2. Execute:
```bash
source pyinfra-venv/bin/activate
pyinfra inventory.py deploy.py
```
*(Pyinfra will automatically execute commands locally using `sudo` where required).*
#### Option B: Remote Deployment (via SSH)
If you are deploying to remote servers, Pyinfra will execute the deployment over SSH.
1. Ensure `K8S_MASTERS` and `K8S_WORKERS` in your `.env` file contain the remote IP addresses or DNS names (e.g., `K8S_MASTERS="192.168.1.10"`).
2. Ensure you have passwordless SSH access configured for the target servers (e.g., using `ssh-copy-id`).
3. Set the appropriate SSH user by uncommenting and configuring `TARGET_USER` in the `.env` file.
1.**Configure Targets in `.env`:** Specify target remote hosts in mandatory `<username>@<ip>` format (note: exactly 1 master node is supported for the control plane):
2.**Execute Deployment & Provide Sudo Passwords:**
```bash
source pyinfra-venv/bin/activate
pyinfra inventory.py deploy.py
pyinfra inventory.py deploy.py-y
```
-**Mandatory Sudo Prompts:** Installing system packages and Kubernetes requires root privileges (`sudo`). PyInfra will interactively prompt you for the sudo password of your `K8S_MASTERS` nodes (and separately for `K8S_WORKERS`, if configured). Press **Enter** if the target account has passwordless sudo enabled on the remote server.
---
## Resuming Interrupted Deployments
The deployment process is **idempotent and checkpointed**:
- Long-running stages (such as compiling `meepctl` binaries and packaging container images) create checkpoint markers automatically.
- If your network disconnects or an execution is interrupted, simply re-run `pyinfra inventory.py deploy.py`.
- The installer will skip all completed stages and resume immediately from the last checkpoint without restarting from scratch.
