CareTogetherCMS

CareTogether is an open-source case management system (CMS) for nonprofits connecting families to caring communities. The wiki provides much more detail about the design of CareTogether. If you prefer to jump straight into the code, keep reading!

Contributing

Thank you for your interest in helping to build this vital tool! If you'd like to jump straight into development, please check out the issues labeled "Help Wanted", which are tasks that have been identified as a good fit for initial contributions and have documentation to support you. They are intentionally not critically time-sensitive, so you can work on them at your own pace. We are tracking the overall status of those issues in the CareTogether Contributions project.

If you have additional time to dedicate to contributing and feel you're ready to take on larger chunks of feature development work, please contact Lars Kemmann to set up an introductory call and request an invite to Teams where we are coordinating the design, development, and support efforts for CareTogether.

Collaboration Guidelines

We ask that you practice effective communication, preferably through comments on the GitHub issues:

1. Let others know that you are interested in working on an issue by leaving a comment.
2. As soon as you start working on an issue, create a draft pull request for it so that others can see any progress you have made.
3. Push changes to your PR frequently! We prefer small incremental commits over large changes that you keep locally for several days, so that others can see your progress.
4. Once you've completed developing and testing your changes locally, publish your draft PR so that maintainers will know to begin a PR review.
5. Stay responsive to comments on your PR.

Prerequisites

You can build and run CareTogether on any operating system supported by Node.js and .NET, including Windows, MacOS, and Linux. Install the following:

• Node.js 18 LTS
• .NET 10
• Visual Studio Code (recommended)

You will also need to allow PowerShell scripts to run on your computer (see documentation). To do this, open an administrative PowerShell session and run the following command: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Development

NOTE: The API project comes with a basic set of test data for local development. This test data is automatically regenerated each time you start the API project.

For frontend route changes, see location routing.

1. Clone the repository into any local directory on your device.
2. Run the CareTogether.Api project and the React client.
   • If using Visual Studio Code (recommended), all you need to do is open the repository folder in VS Code and hit 'F5' to start debugging both the client and server. VS Code will also automatically install and run the Azurite emulator for Azure Storage in your project folder.
   • If using the command line, you will need dotnet run (in the src/CareTogether.Api directory) to start the API, and npm run dev (in the src/caretogether-pwa directory) to start the client. If using another IDE such as Visual Studio, use the equivalent debug or launch options.
3. To sign into the application's local test environment, use the following credentials:
   • Administrator
     • Email Address: [email protected]
     • Password: P@ssw0rd
   • Volunteer
     • Email Address: [email protected]
     • Password: P@ssw0rd

Local Aspire + Keycloak Playwright E2E

The local end-to-end test path uses the Aspire AppHost in src/CareTogether.AppHost to start Keycloak, the API, and the React/Vite frontend. Keycloak imports the local test realm from src/CareTogether.AppHost/Realms/caretogether-local-realm.json, and the AppHost configures the API and frontend to use that local Keycloak realm instead of Azure AD B2C. The AppHost also disables external telemetry and enables local-only feature flag overrides needed by the referral E2E path.

Before running the AppHost Playwright test, make sure these local prerequisites are available:

• Docker Desktop is installed, running, and using the Linux container engine. Keycloak is an Aspire container resource, so docker info must succeed.
• Azurite Blob service is running on 127.0.0.1:10000. The API uses UseDevelopmentStorage=true for local test data. One direct command is azurite-blob --loose from the repository root.
• Port 3000 is free. The local Keycloak realm, API CORS policy, and Vite frontend are intentionally aligned on http://localhost:3000.
• Frontend dependencies are installed with npm ci from src/caretogether-pwa.
• Playwright browsers are installed with npx playwright install from src/caretogether-pwa.

Recommended local verification commands:

docker info
Push-Location src/caretogether-pwa
npm ci
npx playwright install
npm run type-check
npx playwright test --list
Pop-Location
dotnet test test/CareTogether.AppHost.Tests/CareTogether.AppHost.Tests.csproj

Azure AD B2C callback configuration

The frontend uses a lightweight callback document for silent token renewal and popup-based session recovery. Every deployed frontend origin must register /silent-callback.html as a Single-page application redirect URI in the Azure AD B2C app registration. The checked-in environments require:

• http://localhost:3000/silent-callback.html
• https://app.caretogether.io/silent-callback.html

Register the applicable URI before deploying a build that uses it. The callback intentionally contains no application code so MSAL's hidden iframe does not start a second copy of the application.

If the AppHost Playwright test fails before the browser opens, first check Docker and Azurite. The test performs preflight checks for both and should fail with a direct message when either local dependency is unavailable.

Troubleshooting Your Local Setup

1. If pressing 'F5' does not start the project for you in Visual Studio Code, then you likely have a key-mapping issue with your keyboard & will need to instead select "Start Debugging" from Visual Studio Code's "Run" menu
2. If the server side of the application does not start correctly and/or seems to be having issues that you're having trouble debugging, you can try running the "CareTogether.Api" project separately in a different IDE, such as Visual Studio
3. If you're having problems getting the Azurite emulator to run (such as a "No connection could be made because the target machine actively refused it" error on the "tenantContainer.CreateIfNotExists()" method of "TestStorageHelper.cs"), you may need to install & run the Azurite emulator manually. To do so:

• Run npm install -g azurite from the command line
• Navigate to the local repository where you cloned the project
• Run the azurite-blob --loose command to start Azurite from the command line (This will run Azurite with the default Blob service endpoint as we don't use the Queue or Table storage endpoints currently. You can also add a --silent parameter if you don't want to see individual requests logged to the terminal. The --loose parameter is currently required to support valet key access from the browser.)

Licensing Notice

CareTogether is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) which, crucially, only permits hosting this software (including derivatives) if you also make the source code of the software and any of your modifications available to your users under this same license. This effectively ensures that CareTogether CMS remains forever open-source and doesn't simply become the base code for a proprietary derivative at some point. We value collaboration and openness, and we believe that the best way to accomplish this is to ensure the software remains open to everyone.

Licensing Exemption

The CareTogether name and logo are exempt from the AGPL-3.0 license as they remain the property of Coept LLC. Among other things, this means that you are not allowed to brand or advertise your hosted version of this software as being the CareTogether CMS without express written permission from Coept LLC. This is intended both to protect the business interest of Coept LLC in providing the CareTogether hosted service and to protect against impersonation of the CareTogether hosted service by third parties.