Skip to content

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+

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

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

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

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