# Mifos X + Fineract on r630-02 — Deployment Runbook

**Last Updated:** 2026-02-09  
**Status:** Active  
**Host:** r630-02 (192.168.11.12)  
**VMID:** 5800  
**IP:** 192.168.11.85  
**Domain:** mifos.d-bis.org (Cloudflare Tunnel + UK egress)

**Remaining steps after automated setup:** [MIFOS_REMAINING_STEPS.md](MIFOS_REMAINING_STEPS.md)  
**Optional — tunnel via NPMplus:** [MIFOS_NPMPLUS_TUNNEL.md](MIFOS_NPMPLUS_TUNNEL.md) (dedicated NPMplus VM 10237 → 5800).

---

## Overview

- **LXC 5800** on r630-02 runs Ubuntu 24.04 (or 22.04), Mifos X + Apache Fineract, and **cloudflared** in the same container.
- Traffic reaches the app via **Cloudflare Tunnel** (no port forwarding on Proxmox).
- **UK egress** is configured via Cloudflare Regional Services for the hostname.

---

## 1. Create LXC 5800 on r630-02

From the project root:

```bash
./scripts/create-mifos-lxc-r630-02.sh
```

Optional: `--dry-run` to print the create command without running it.

**Overrides:** `MIFOS_IP`, `STORAGE_R630_02_MIFOS` (default `thin3`), `TEMPLATE_UBUNTU_24`.

---

## 2. Install Mifos X + Fineract inside LXC 5800

**Automated:** Run `./scripts/mifos/install-mifos-docker-in-5800.sh` from project root (installs Docker, downloads Mifos 24.04.30, `docker compose up -d`). If AppArmor blocks containers, add a `docker-compose.override.yml` with `security_opt: [apparmor=unconfined]` per service (see [scripts/mifos/docker-compose.override-apparmor.yml](../../scripts/mifos/docker-compose.override-apparmor.yml)) and re-run `docker compose up -d` in the container.

Or SSH to the container (from a host that can reach r630-02):

```bash
ssh root@192.168.11.12 "pct exec 5800 -- bash"
```

### Option A — Docker (recommended, Mifos 24.04.30)

1. Install Docker: [Docker Engine — Ubuntu](https://docs.docker.com/engine/install/ubuntu/).
2. Download and run:
   - [mifosplatform-24.04.30.RELEASE.zip](https://sourceforge.net/projects/mifos/files/Mifos%20X/mifosplatform-24.04.30.RELEASE.zip/download)
   - Unzip, then:
     ```bash
     cd mifosplatform-24.04.30.RELEASE/docker/mifosx-mariadb
     docker compose pull && docker compose up -d
     ```
3. App listens on **port 80**. Default login: `mifos` / `password` (change after first login).

### Option B — Native (Mifos 25.03.22, Tomcat + MariaDB + OAuth)

Follow [Mifos X 25.03.22 — Ubuntu 24.04 LTS, MariaDB and OAuth](https://mifosforge.jira.com/wiki/spaces/docs/pages/4472635393). App typically on **port 8080**. For tunnel ingress use `http://127.0.0.1:8080` and update the tunnel config/Public Hostname accordingly.

---

## 3. Cloudflare Tunnel (terminate at LXC)

### 3.1 Create tunnel in Cloudflare

1. **Zero Trust** → **Networks** → **Tunnels** → **Create a tunnel**.
2. Connector: **Cloudflared**. Name: `mifos-r630-02`.
3. Copy the **tunnel token**.

### 3.2 Install cloudflared in LXC 5800

From project root (token from 3.1):

```bash
./scripts/install-tunnel-mifos-r630-02.sh '<TUNNEL_TOKEN>'
```

Or set in `.env` (do not commit):

```bash
CLOUDFLARE_TUNNEL_TOKEN_MIFOS_R630_02='eyJ...'
```

Then:

```bash
./scripts/install-tunnel-mifos-r630-02.sh
```

### 3.3 Configure Public Hostname (Published application routes)

**Option A — HTTP to origin (simplest)**  
- **Service:** `http://192.168.11.85:80` (or `http://127.0.0.1:80`). No SSL on origin.

**Option B — HTTPS to origin**  
1. Install Nginx + self-signed cert on 5800 (run from project root):
   ```bash
   ./scripts/mifos/install-nginx-https-5800.sh
   ```
2. In **Zero Trust** → **Tunnels** → **mifos-r630-02** → **Published application routes**, set **Service** to `https://192.168.11.85:443`.
3. Add an **Origin configuration** for this route: enable **No TLS Verify** (so cloudflared accepts the self-signed cert). Without this, 530 can occur.

### 3.4 DNS

- **DNS** for d-bis.org: **CNAME** `mifos` → `<tunnel-id>.cfargotunnel.com`, **Proxied** (orange cloud).

---

## 4. UK egress (Regional Services)

- In Cloudflare: **Zero Trust** or **Data Localization** → **Regional Services**.
- Attach to hostname **mifos.d-bis.org** and select a **region that includes the UK** (e.g. United Kingdom or EU).
- Reference: [Cloudflare Regional Services](https://developers.cloudflare.com/data-localization/regional-services/).

---

## 5. Verification

| Check | Command or action |
|-------|-------------------|
| Tunnel healthy | Zero Trust → Tunnels → mifos-r630-02 status |
| Service in container | `ssh root@192.168.11.12 "pct exec 5800 -- systemctl status cloudflared"` |
| DNS | `dig mifos.d-bis.org` (proxied → Cloudflare IPs) |
| App | `curl -I https://mifos.d-bis.org` → 200 or login page |
| UK egress | Response header `Cf-Ray` or Cloudflare analytics (colo in UK) |

---

## 6. Config and secrets

- **VMID → host:** 5800 → r630-02 in `scripts/lib/load-project-env.sh` (`get_host_for_vmid`).
- **IP:** `MIFOS_IP=192.168.11.85` in `config/ip-addresses.conf`.
- **Public IP (direct access):** `PUBLIC_IP_MIFOS=76.53.10.41`; see [MIFOS_CLOUDFLARE_AND_UDM_76_53_10_41.md](MIFOS_CLOUDFLARE_AND_UDM_76_53_10_41.md) and [UDM_PRO_MIFOS_76_53_10_41_PORT_FORWARD.md](UDM_PRO_MIFOS_76_53_10_41_PORT_FORWARD.md).
- **Tunnel token:** Store as `CLOUDFLARE_TUNNEL_TOKEN_MIFOS_R630_02` in `.env`; documented in [REQUIRED_SECRETS_SUMMARY.md](REQUIRED_SECRETS_SUMMARY.md).
- **Cloudflare API:** Put `CLOUDFLARE_EMAIL` and `CLOUDFLARE_API_KEY` (or `CLOUDFLARE_API_TOKEN`) in `.env`; then run `MIFOS_DNS_MODE=tunnel ./scripts/cloudflare/configure-mifos-dns.sh` or `MIFOS_DNS_MODE=direct` for A record to 76.53.10.41.

---

## 7. Reference config (ingress only)

See [scripts/cloudflare-tunnels/configs/tunnel-mifos-r630-02.yml](../../scripts/cloudflare-tunnels/configs/tunnel-mifos-r630-02.yml) for the ingress shape (tunnel id and credentials are token-driven).