bnkops/Changemaker
bnkops/Changemaker
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Changemaker/README.md
admin 03b38dbd6f readme updates
2025-05-15 12:50:12 -06:00

15 KiB
Executable File
Raw Permalink Blame History

Changemaker V5

changemakergif

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

Contents

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
  • Scheduling: Looking at rally
  • Support and user chat: looking at chatwoot
  • Mass community chat: looking at thelounge
  • Team chat and project management: looking at 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 - ✅
  • 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

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

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

For local development, cloudflare credentials can be ignored.

See Setting Up Cloudflare Credentials for how to get cloudflare credentials for config.sh.

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

The local homepage - 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
Homepage (local) 3011 http://locahost:3011
Homepage 3010 http://localhost:3010
Excalidraw 3333 http://localhost:3333
Listmonk 9000 http://localhost:9000
Monica CRM 8085 http://localhost:8085
MkDocs 4000 http://localhost:4000
Flatnotes 8089 http://localhost:8089
Code Server 8888 http://localhost:8888
Ollama 11435 http://localhost:11435
OpenWebUI 3005 http://localhost:3005
Gitea 3030 http://localhost:3030
Portainer 8005 https://localhost:9444
Mini QR 8081 http://localhost:8081
Ferdium 3009 http://localhost:3009
Answer 9080 http://localhost:9080
NocoDB 8090 http://localhost:8090
n8n 5678 http://localhost:5678
ConvertX 3100 http://localhost:3100
Rocket.Chat 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 - 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 - 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 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

Verify that Docker and Docker Compose are installed correctly:

docker --version
docker compose version

2. Clone the Repository

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 → 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)

# Make the script executable
chmod +x config.sh

# Run the configuration wizard
./config.sh

Option B: Configure manually

# Edit the .env file with your settings
nano .env

4. Start the Services

# 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

Configure Your Cloudflare Tunnel

You can use our Cloudflare Configuration Guide however remember to copy the values of the example config for this deployment.

Create a Cloudflare System Service

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

[!warning] Deleting DNS Records

Running this script will delete all DNS records that are connected to this Cloudflare account.

# 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 applications without access control. 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. It will also allow your set admin email access to these applications. 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: 
    cd /home/coder/mkdocs
mkdocs build

Option 2: Locally on your machine

  1. Navigate to the mkdocs directory in your project: 
    cd /home/bunker-admin/Changemaker/mkdocs
  2. Run the build command: 
    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:

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:

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:

Troubleshooting

If you encounter issues:

  1. Check the Docker logs:

    docker compose logs

  2. Verify service status:

    docker compose ps

  3. Ensure your Cloudflare Tunnel is running:

    sudo systemctl status cloudflared

  4. Check CNAME records in your Cloudflare dashboard.

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