FOSS United Platform – Developer Guide¶

The FOSS United Platform is developed and maintained by the FOSS United Foundation, with ongoing contributions from the community. Development takes place on GitHub.

Note: We welcome contributions from anyone. Join us by submitting issues, feature requests, or pull requests!

Installation Guide¶

Recommended Frappe Version: v15+

Recommended: Setup & Quick-start¶

Our recommended setup is via docker + frappe manager.

• Install uv python manager and docker
• uv init in a new directory
• uv add frappe-manager
• uv run fm create foss.localhost
• uv run fm start — choose site as it shows in menu
• uv run fm shell — enter into docker container shell and run further steps there
• For frappe >= v16, install newsletter first:
• bench get-app https://github.com/frappe/newsletter
• bench --site foss.localhost install-app newsletter
• bench get-app https://github.com/fossunited/fossunited.git
• bench --site foss.localhost install-app fossunited — this will also install dashboard
• Configure frappe for server scripts and developer mode:
• bench set-config -g server_script_enabled true
• bench --site foss.localhost set-config developer_mode 1

• bench --site foss.localhost migrate

• To run tests please create new-site since it can have unintended DB changes.

• bench new-site break.site
• For frappe >= v16: bench --site break.site install-app newsletter
• bench --site break.site install-app fossunited

• bench --site break.site set-config allow_tests true

• Open foss.localhost in your browser and start exploring!

• Dashboard page can be accessed via foss.localhost/dashboard

Note: Since dashboard is not running as live dev server, you'd need to bench build --apps fossunited for changes to update.

If you would prefer for manual method, please follow on below

Manual Install¶

1. Prerequisites¶

• Set up your environment using the official Frappe installation guide.
• If you encounter a MariaDB password issue, refer to this DigitalOcean guide to reset your root password.

If the kill command fails:

ps aux | grep mysqld
sudo kill -9 <pid_of_mysqld> <pid_of_mysql_safe>

Ensure MySQL processes are fully stopped before restarting.

2. Setup Steps¶

# Create a new bench
bench init fossu-bench
cd fossu-bench

Install Newsletter App¶

For frappe >= v16, the Newsletter module has been moved as an separate app. Install it before fossunited:

bench new-site foss.localhost
bench get-app https://github.com/frappe/newsletter
bench --site foss.localhost install-app newsletter

Related discussion: #1120

Install FOSS United App¶

# Get the app
bench get-app https://github.com/fossunited/fossunited

# Install the app on the site
bench set-config -g server_script_enabled true
bench --site foss.localhost install-app fossunited
bench --site foss.localhost set-config developer_mode 1
bench --site foss.localhost migrate

# Start development server
bench start

To access the site in your browser, follow:
Access Site via Browser

NixOS Setup¶

For those using NixOS, refer to this guide ==> Issue #1068 – NixOS Setup Guide to get going.

FOSS United Dashboard¶

The Dashboard is an admin UI for volunteers to manage activities across FOSS Clubs and City Chapters.

Dashboard Setup¶

# Go to the dashboard directory
cd fossunited/dashboard

# Install dependencies
yarn install

Required Configuration¶

In your site_config.json, add the following:

{
  "ignore_csrf": 1
}

Run the Dashboard¶

yarn dev

The dashboard will be available at:
==> http://<your-site-name>:8080

Seed Script¶

The seed script populates a fresh site with realistic development data so you
can explore the full platform immediately after install — chapters, events,
RSVPs, CFPs, and a hackathon — without having to create records manually.

Running the Script¶

podman exec -w /workspace/development/fossu-bench/sites devcontainer-frappe-1 \
    ../env/bin/python /workspace/development/run_seed.py

The script is idempotent — running it multiple times on the same database
is safe. Existing records are detected and skipped.

Data Hierarchy¶

The script creates a tree of related records:

Users (8)
├── Attendees (2)          attendee-{1,2}@example.com
├── Speakers (2)           speaker-{1,2}@example.com
└── Chapter Leads (4)      {bangalore,mumbai,kochi,campus}[email protected]

Chapters (4)
├── FOSS Bangalore          City Community
├── FOSS Mumbai             City Community
├── FOSS Kochi              City Community
└── Campus Chapter          Student Club

Events (12)  — one of each template per City Community chapter
├── FOSS Meetup 2026        status: Live     (3 chapters × 1)
├── FOSS Conference 2025    status: Concluded
├── FOSS Workshop 2026      status: Draft    (unpublished)
└── Mini FOSS Hackathon     status: Live

RSVPs (6 forms)  — one per Live event, each with 2 submissions
CFPs  (6 forms)  — one per Live event, each with 2 talk submissions

Hackathon — FOSSIT Hackathon (Campus Chapter)
├── Teams (4)              Phoenix / Aurora / Nebula / Comet
├── Localhost (1)          Kochi LocalHost
└── Projects (4)           one per team

What each Doctype represents:

Reviewer Workflow Demo¶

To test the Pretalx-inspired reviewer workflow with pre-populated demo data, use the provided demo script:

./development/demo.sh

This script will:
1. Start the necessary containers (MariaDB, Redis, Frappe).
2. Setup a local Frappe bench.
3. Build the Vite-based dashboard.
4. Seed demo data including events, CFP submissions, and a demo reviewer.

Access Details:
- URL: http://fossunited.localhost:8000
- Demo Reviewer: [email protected]
- Password: password (default for all seeded users)

The demo uses your local repository changes, allowing for rapid iteration and testing of the new reviewer experience.

What to Expect in the UI¶

Default Credentials¶

All seed users share the same password.

Pre-commit Hooks¶

To automatically run linters before commits:

• We use ruff for linting python files. It is recommended to use prettier for formatting HTML, CSS & Vue files.
• Vale is used for spell check and grammar check for docs content.

uv add pre-commit
pre-commit install

Or use uv as an alternative Python package manager.

Troubleshooting¶

Common Issues¶

• MariaDB root password error — follow this guide to reset it
• Site shows errors after install — make sure you ran bench --site foss.localhost migrate
• Server scripts not running — verify server_script_enabled is set to true
• tatsu crash during install — a recent tatsu release is broken. Fix it by downgrading and using --force:

./env/bin/pip install "tatsu<5.10.0"
bench --site foss.localhost install-app --force fossunited

See #1320 for more context on this issue.

macOS + Colima Setup¶

If you're using Colima instead of Docker Desktop, here are the fixes for the common errors you'll hit:

1. Docker socket not found

sudo ln -sfn ~/.colima/default/docker.sock /var/run/docker.sock

2. Missing Compose plugin

mkdir -p ~/.docker/cli-plugins
ln -sfn $(which docker-compose) ~/.docker/cli-plugins/docker-compose

3. UID 1000 crash

SITE_PKGS="$(uv run python -c 'import sysconfig; print(sysconfig.get_paths()["purelib"])')"
find "$SITE_PKGS/frappe_manager" -type f -name "*.py" -exec sed -i '' 's/os.getuid()/1000/g' {} +
find "$SITE_PKGS/frappe_manager" -type f -name "*.py" -exec sed -i '' 's/os.getgid()/1000/g' {} +

4. uv install failing (os error 1)

Run these inside fm shell before bench get-app:

export UV_CACHE_DIR=/tmp/uv_cache
export UV_LINK_MODE=copy

5. Dashboard build crash (exit code 137)

Colima's default RAM is too low for the Vite build. Restart with more resources:

colima start --cpu 4 --memory 8

Full discussion and all fixes: #1320

Useful Links¶

• FOSS United GitHub repo
• Frappe Docs
• Create a Site Guide

Happy hacking! If you face issues, open a GitHub issue or join the FOSS United community for help.