# Changemaker V5

![changemakergif](/assets/images/changemkaerv5.gif)

---

Changemaker V5 is a battle-tested, lightweight, self-hosted productivity suite which empowers you to deploy secure, locally-built websites, blogs, newsletters, & forms – from personal projects to full-fledged campaigns – granting you complete control, inherent security, and true freedom of speech. 

It is a project undertaken by The Bunker Operations, headquarted in Edmonton, Alberta, Canada, as to provide our community a digital campaign alternative to mainstream American systems. 

![build your power](/assets/images/buildyourpower.png)

## Contents
- [Prerequisites](#prerequisites)
- [Quick Start](#quick-start)
- [Detailed Installation](#detailed-installation)
  - [1. Install Docker and Docker Compose](#1-install-docker-and-docker-compose)
  - [2. Clone the Repository](#2-clone-the-repository)
  - [3. Configure Your Environment](#3-configure-your-environment)
  - [4. Start the Services](#4-start-the-services)
  - [5. Run Post-Installation Tasks](#5-run-post-installation-tasks)
- [Local Service Ports](#local-service-ports)
- [Cloudflare Tunnel Setup](#cloudflare-tunnel-setup)
  - [Install Cloudflared on Ubuntu 24.04](#install-cloudflared-on-ubuntu-2404)
  - [Configure Your Cloudflare Tunnel](#configure-your-cloudflare-tunnel)
  - [Create a Cloudflare System Service](#create-a-cloudflare-system-service)
  - [Add CNAME Records](#add-cname-records)
- [Website Build and Deployment Workflow](#website-build-and-deployment-workflow)
- [Reset Your Installation](#reset-your-installation)
- [Accessing Your Services](#accessing-your-services)
- [Troubleshooting](#troubleshooting)

---
## Development Pathway 

Changemaker's identified wants for development: 
- Internal integrations for assset management i.e. shared plain file locations 
- Database connections for automation systems i.e. manauls for Nocodb & n8n on connecting services
- Manual & landing site for the whole system i.e. upgrading bnkops.com 
- Trainings and manuals across the board 

Idenitfied Feature Requests: 
- Event Management: Looking at [hi.ewvents](https://hi.events/)
- Scheduling: Looking at [rally](https://rallly.co/)
- Support and user chat: looking at [chatwoot](https://github.com/chatwoot/chatwoot)
- Mass community chat: looking at [thelounge](https://thelounge.chat/)
- Team chat and project management: looking at [rocket chat](https://github.com/RocketChat/Rocket.Chat) ✔️

Bugs:
- Readme needs a full flow redo - ✅ next up 
- Config script needs to be updated for nocodb for a simpler string / set the string - :white_check_mark:
- Gitea DNS application access bypass not properly setting - ✅ bypass needing manual setup / need to explore api more
- Portainer not serving to http - 🤔 portainer to be limited to local access 
- nocodb setup upping odd - ✅ password needs no special characters
- ferdium port mismatch - ✅ was a cloudflare port setting missmatch

## Prerequisites

- A Linux server (Ubuntu 22.04/24.04 recommended)
- Docker & Docker Compose
- Internet connection
- (Optional) Root or sudo access
- (Optional) A domain name for remote access
- (Optional) Cloudflare account for tunnel setup

## Quick Start for Local Dev

Review all off the applications [here](/apps.md)

If you're familiar with Docker and want to get started quickly:

```bash
# Clone the repository
git clone https://gitea.bnkhome.org/bnkops/Changemaker.git
cd changemaker
```

See [Setting Up Cloudflare Credentials](#setting-up-cloudflare-credentials) for how to get cloudflare credentials for config.sh.

```bash
# Use default configuration for local development.
# To configure for remote deployment with Cloudflare, first make the script executable:
chmod +x config.sh

# Then run the configuration script. You will need your Cloudflare details.
./config.sh
```

```
# Start all services
docker compose up -d
```

**First time installation can take several miniutes**

On a 1GB internet connection, instal time is approximately 5 minutes.

### ⚠️ Configure Portainer Immediately 🦊

Portainer has a timed build process that needs to be completed on successful build. Proceed to configure the service by visiting https://localhost:9444 

Gitea has a install process that you should complete immediately after connecting system to dns and domain services. 

### On Successful Build, Vist [Local Homepage](http://localhost:3011)
The [local homepage - http://localhost:3011](http://localhost:3011) is configured with all of the services you can access securely locally. 

To access services outside of network, configure a VPN, Tailscale, or continue to Cloudflare publishing documentation.

## Local Service Ports

When running Changemaker locally, you can access the services at the following ports on your server:

| Service      | Local Port | Local URL                                |
|--------------|------------|------------------------------------------|
| Root/Website (Nginx) | 4001       | [http://localhost:4001](http://localhost:4001)         |
| Homepage (local) | 3011 | [http://locahost:3011](http://localhost:3011)            |
| Homepage     | 3010       | [http://localhost:3010](http://localhost:3010)         |
| Excalidraw   | 3333       | [http://localhost:3333](http://localhost:3333)         |
| Listmonk     | 9000       | [http://localhost:9000](http://localhost:9000)         |
| Monica CRM   | 8085       | [http://localhost:8085](http://localhost:8085)         |
| MkDocs       | 4000       | [http://localhost:4000](http://localhost:4000)         |
| Flatnotes    | 8089       | [http://localhost:8089](http://localhost:8089)         |
| Code Server  | 8888       | [http://localhost:8888](http://localhost:8888)         |
| Ollama       | 11435      | [http://localhost:11435](http://localhost:11435)       |
| OpenWebUI    | 3005       | [http://localhost:3005](http://localhost:3005)         |
| Gitea        | 3030       | [http://localhost:3030](http://localhost:3030)         |
| Portainer    | 8005       | [https://localhost:9444](https://localhost:9444)         |
| Mini QR      | 8081       | [http://localhost:8081](http://localhost:8081)         |
| Ferdium      | 3009       | [http://localhost:3009](http://localhost:3009)         |
| Answer       | 9080       | [http://localhost:9080](http://localhost:9080)         |
| NocoDB       | 8090       | [http://localhost:8090](http://localhost:8090)         |
| n8n          | 5678       | [http://localhost:5678](http://localhost:5678)       |
| ConvertX     | 3100       | [http://localhost:3100](http://localhost:3100)         |
| Rocket.Chat  | 3004       | [http://localhost:3004](http://localhost:3004)         |

### Ubuntu OS & Build Outs

You can deploy Changemaker on any OS using Docker however we also provide several full Ubuntu build-outs. These scripts can speed up your deployment immensely and Changemaker is developed on a like system: 

1. **[build.server](https://gitea.bnkhome.org/bnkops/scripts/src/branch/main/build.server.md)** - this build-out is a lightweight deployment aimed for dedicated server machines. It is focused on entry level users who would build on a dedicated machine. 
2. **[build.homelab](https://gitea.bnkhome.org/bnkops/scripts/src/branch/main/build.homelab.md)** - this build-out is full-some development focused build-out that The Bunker Operations uses for our day-to-day operations. 

Configuration and services scripts for futher developing the system can be found at the [scripts](https://gitea.bnkhome.org/bnkops/scripts) repo. 

### 1. Install Docker and Docker Compose

Install Docker and Docker Compose on your system if they're not already installed: 

[Install Docker & Docker Compose](https://gitea.bnkhome.org/bnkops/scripts/src/branch/main/build.homelab.md#dockerhttpswwwdockercom)

Verify that Docker and Docker Compose are installed correctly:

```bash
docker --version
docker compose version
```

### 2. Clone the Repository

```bash
git clone https://github.com/your-org/changemaker-v5.git
cd changemaker-v5
```

### 2. Configure Your Environment

#### Setting Up Cloudflare Credentials

To use the  script, you'll need to collect several Cloudflare variables: 

1. **Create an API Token with appropriate permissions**:
   - Go to your [Cloudflare Dashboard](https://dash.cloudflare.com/) → Profile → API Tokens
   - Click "Create Token"
   - Either use the "Edit zone DNS" template or create a custom token with:
     - Zone:DNS:Edit permissions
     - Access:Apps:Edit permissions
   - Restrict the token to only your specific zone/domain
   - Generate and copy the token

2. **Get your Zone ID**:
   - Go to your domain's overview page in the Cloudflare dashboard
   - The Zone ID is displayed on the right sidebar
   - It looks like: `023e105f4ecef8ad9ca31a8372d0c353`

3. **Get your Tunnel ID**:
   - You should have noted your tunnel id in your tunnel creation or you can find it through cloudflare or in your files: 
   - Go to Cloudflare Zero Trust dashboard → Access → Tunnels
   - Click on your tunnel
   - The Tunnel ID is in the URL: `https://dash.teams.cloudflare.com/xxx/network/tunnels/xxxx`
   - It looks like: `6ff42ae2-765d-4adf-8112-31c55c1551ef`

You have two options:

**Option A: Use the configuration wizard (recommended)**
```bash
# Make the script executable
chmod +x config.sh

# Run the configuration wizard
./config.sh
```

**Option B: Configure manually**
```bash
# Edit the .env file with your settings
nano .env
```

### 4. Start the Services

```bash
# Pull and start all containers in detached mode
docker compose up -d
```

   > [!Warning] Configure Portainer 

   Portainer has a timed build process. Make sure to immediatly configure the service at https://localhost:9444 following successful build. 


All services can now be accessed through on local machine. If deploying to public, it is recommended to **configure portainer** and then continue configuration for all other services once tunnel is established. Then use the public links for configuration of services. For online deployment with Cloudflare, continue to next steps. 

### 4. Cloudflare Tunnel Setup

For secure remote access to your services, you can set up a Cloudflare Tunnel.

### Install Cloudflared on Ubuntu 24.04

[Cloudflared Installation Guide](https://gitea.bnkhome.org/bnkops/scripts/src/branch/main/build.homelab.md#cloudflaredhttpsdeveloperscloudflarecomcloudflare-oneconnectionsconnect-networks)

### Configure Your Cloudflare Tunnel

You can use our [Cloudflare Configuration Guide](https://gitea.bnkhome.org/bnkops/scripts/src/branch/main/config.cloudflare.homelab.md) however remember to copy the values of the [example config](/example.cloudflare.config.yml) for this deployment. 

### Create a Cloudflare System Service

[Cloudflare Service Setup Guide](https://gitea.bnkhome.org/bnkops/scripts/src/branch/main/service.cloudflared.md)

### Add CNAME Records

After setting up your Cloudflare Tunnel, you need to add CNAME records for your services. You can do this manually in the Cloudflare DNS panel or with using the following script: `add-cname-records.sh`

```bash
# Make the script executable
chmod +x add-cname-records.sh

# Run the script to add CNAME records
./add-cname-records.sh
```

This script will add CNAME records for all Changemaker services to your Cloudflare DNS.

It will also set up a Cloudflare Access Application for all services execpt for your website and gitea. This is a extra layer of security that we do recommend for your deployment. It will automatically allow any emails with from the root domain that you set in the `config.sh` process. For example, if you set your root domain to `example.com` your access rule will allow emails ending with @example.com thorugh. You can update your access settings in the Cloudflare Zero Trust dashboard.

> [!warning] ⚠️ Cloudflare Zero Trust ⚠️

   To ensure that system is secure, we highly recommend setting up some level of access control using Cloudflare Zero Trust. The `add-cname-records.sh` will do this automatically however the user is encouraged to familiarize themselves with Cloudflares Zero Trust access system. 

## Website Build and Deployment Workflow

Changemaker uses MkDocs to create your website content, which is then served by an Nginx server. To update your website, you need to:

1. **Edit your content** using either the Code Server or locally on your machine
2. **Build the static site files** 
3. **Let the Nginx server (mkdocs-site-server) serve the built site**

### Building Your Website

You can build your website in two ways:

#### Option 1: Using Code Server (recommended for remote deployments)
1. Access Code Server at http://localhost:8888 or https://code-server.yourdomain.com
2. Navigate to the mkdocs directory `/home/coder/mkdocs/`
3. Open a terminal in Code Server
4. Run the build command:
   ```bash
   cd /home/coder/mkdocs
   mkdocs build
   ```

#### Option 2: Locally on your machine
1. Navigate to the mkdocs directory in your project:
   ```bash
   cd /home/bunker-admin/Changemaker/mkdocs
   ```
2. Run the build command:
   ```bash
   mkdocs build
   ```

After building, the static site files will be generated in the `mkdocs/site` directory, which is automatically mounted to the Nginx server (mkdocs-site-server). Your website will be immediately available at:
- Locally: http://localhost:4001
- With Cloudflare: https://yourdomain.com

### Development vs Production

- During **development**, you can use the MkDocs live server at port 4000, which automatically rebuilds when you make changes
- For **production**, build your site as described above and let the Nginx server at port 4001 serve the static files

## Accessing Your Services

The **Homepage** acts as a central dashboard for all your Changemaker services. You can access it at:

- Locally: http://localhost:3010 or http://your-server-ip:3010
- With Cloudflare: https://homepage.yourdomain.com

The Homepage will display links to all your deployed services, making it easy to navigate your Changemaker ecosystem.

After installation and cloudflare deployment you can also access individual services at the following URLs:

- Website: https://yourdomain.com
- Homepage: https://homepage.yourdomain.com
- Excalidraw: https://excalidraw.yourdomain.com
- Listmonk: https://listmonk.yourdomain.com
- Monica CRM: https://monica.yourdomain.com
- MkDocs: https://yourdomain.com
- Flatnotes: https://flatnotes.yourdomain.com
- Code Server: https://code-server.yourdomain.com
- Ollama: https://ollama.yourdomain.com
- OpenWebUI: https://open-web-ui.yourdomain.com
- Gitea: https://gitea.yourdomain.com
- Portainer: https://portainer.yourdomain.com
- Mini QR: https://mini-qr.yourdomain.com
- Ferdium: https://ferdium.yourdomain.com
- Answer: https://answer.yourdomain.com
- NocoDB: https://nocodb.yourdomain.com
- n8n: https://n8n.yourdomain.com
- ConvertX: https://convertx.yourdomain.com
- Rocket.Chat: https://rocket.yourdomain.com

## Troubleshooting

If you encounter issues:

1. Check the Docker logs:
   ```bash
   docker compose logs
   ```

2. Verify service status:
   ```bash
   docker compose ps
   ```

3. Ensure your Cloudflare Tunnel is running:
   ```bash
   sudo systemctl status cloudflared
   ```

4. Check CNAME records in your Cloudflare dashboard.


For additional help, please file an issue on our GitHub repository.