# Open Collective Monorepo
A centralized workspace for all Open Collective projects, providing a unified development environment with shared configurations, devcontainers, and tools.
This workspace serves as:
- **Central Development Hub**: Clone and setup all Open Collective projects at once
- **DevContainer Configuration**: Quick development environment setup with Docker
- **Shared IDE Configuration**: VS Code workspace settings and extensions
- **Common Tools & Configs**: Shared configs, scripts, and development utilities
## Why use this monorepo?
1. It makes the whole setup easier. Dependencies are started automatically (in Docker).
2. Dev containers make it safer to run the code, and will especially limit:
- Attacks through the dependency chain (local packages don't get access to the host)
- Prompt injection attacks when using an agent
To take full advantage of these benefits, it is recommended that you go through the "Additional recommendations" section below after setting up the monorepo.
## Getting Started
For a persistent development microVM with SSH/editor access, follow
[the microsandbox guide](.vm/README.md). Run `./.vm/setup.sh` from the primary
checkout after installing microsandbox and enabling KVM access. The
`.vm/opencollective-msb.yaml` config defaults to 8 CPUs and 32 GiB RAM. Setup mounts
the host checkout at `/workspace` and installs the toolchain and Docker inside the
sandbox. Configure SSH editor access and external worktree mounts manually. Use native
`msb` commands for administration. The DevContainer workflow below remains available.
### Prerequisites
- Git
- Docker or Podman (for the recommended DevContainer setup)
- Alternatively, check each project's README for manual setup instructions
### 1. Clone the Workspace
```bash
git clone https://github.com/opencollective/monorepo.git opencollective
cd opencollective
./scripts/init.sh
```
This initializes all Open Collective projects as Git submodules and checks out the latest `origin/main` on a local `main` branch. Every subsequent run fetches and updates the projects again.
To clone only the projects you need (faster setup, less disk use):
```bash
./scripts/init.sh --projects api,frontend,documentation
```
Use short names (`api`, `frontend`, `documentation`, …) or full directory names (`opencollective-api`). Only selected projects are cloned or updated. Combine with `--shallow` for smaller initial clones. Run `./scripts/init.sh --help` for all options.
The devcontainer below requires the API and frontend repositories, including the API's Docker Compose files.
### Working with the project repositories
Commit and push service changes from the service's own directory. Submodules use `ignore = all`, so edits, commits, and branch switches inside them do not appear as changes in the workspace repository. Explicitly staged submodule commit pointers still appear and can be committed.
Rerunning `init.sh` switches selected projects back to `main` and fast-forwards them to the latest `origin/main`. Feature branches remain available. If a project has uncommitted changes or commits on `main` that are not on `origin/main`, the script preserves that work, reports an error, and continues updating the other projects. It exits with a nonzero status if any project fails. Commit or stash uncommitted changes, or reconcile local `main` commits, before retrying.
Existing repositories cloned by older versions of the setup script are adopted as submodules automatically. The script does not stage updated submodule commit pointers in the workspace.
Git records a commit pointer for each submodule, but the setup script intentionally follows the latest `main` rather than those recorded commits. Plain `git submodule update --init` uses the recorded commits and usually leaves a detached HEAD; use `./scripts/init.sh` for this development workflow.
### 2. Open in VS Code with DevContainer (Recommended)
DevContainers give you a fully configured development environment with all dependencies ready to go.
1. Install the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
2. Open the monorepo in VS Code or Cursor.
3. Press `Ctrl+Shift+P` (or `Cmd+Shift+P` on Mac) and select **"Dev Containers: Reopen in Container"**
VS Code will start with PostgreSQL, Mailpit, and other services running automatically.
### 3. Start the Application
Run the start script to launch the frontend and API:
```bash
run
```
**Access the app:**
- Frontend: [http://localhost:3000](http://localhost:3000)
- API: [http://localhost:3060](http://localhost:3060)
- Mail server: [http://localhost:1080](http://localhost:1080)
**Start specific services:**
```bash
run frontend # Frontend only
run frontend api # Frontend and API
run frontend:staging # Frontend connected to staging
```
---
## Running Tests
Use the unified test script to run tests across any project:
```bash
# Run a specific test file
test opencollective-frontend/components/MyComponent.test.tsx
# Run tests in watch mode
test --watch opencollective-api/test/server/lib/mylib.test.ts
```
The script automatically detects the project (frontend, api, pdf, rest) and runs the appropriate test command.
## Shell shortcuts
In the devcontainer, `run` and `test` aliases are set up automatically. Outside the devcontainer, use `./scripts/run.sh` and `./scripts/test.sh`. If you get `run: command not found`, restart the devcontainer.
---
## Additional recommendations
- **NEVER** store production secrets in these repositories. If you need to use production secrets, clone a separate instance of the repository that is dedicated to that purpose, and never use it with agents/for development.
- In VSCode settings, set `dev.containers.enableGPGAgentForwarding` and `dev.containers.enableSSHAgentForwarding` to false, and use git from the host machine. This will prevent the dev container from using the host machine's git configuration, which could be exploited by malicious code to silently push updates.
---
## Manual Setup (Without DevContainer)
If you prefer not to use DevContainers:
1. Start dependencies: `./scripts/start-dependencies.sh --detach db mail uploads`
2. Navigate to individual project directories (`opencollective-api`, `opencollective-frontend`)
3. Follow the setup instructions in their README files