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
  • fm create foss.localhost
  • fm start choose site as it shows in menu
  • fm shell (enter into docker container shell and run further steps there)
  • bench get-app https://github.com/fossunited/fossunited.git
  • bench install-app fossunited - This will also install dashboard
  • Also please configure frappe for server scripts and running tests

  • bench set-config -g server_script_enabled true

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

  • bench new-site break.site

  • 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 get-app https://github.com/frappe/newsletter
bench install-app newsletter

Related discussion: #1120

Install FOSS United App
# Get the app
bench get-app https://github.com/fossunited/fossunited

# Create a new site
bench new-site test.localhost

# Install the app on the site
bench --site test.localhost install-app fossunited

# 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.

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