Actual Chat

Web site: actual.chat

Join Team Chats

• Unsurprisingly, our team uses Actual Chat to communicate
• If you're a part of our team, please contact Alex Yakunin to get access.

Prerequisites

Install:

• Git
• .NET 8
• dotnet workload install wasm-tools maui aspire
• Docker
• NodeJS 16+ and the latest npm; npm-windows-update is the simplest way to update npm on Windows
• Edge or Chrome
• Playwright
• Configure GCP service key
• Ensure your time & timezone settings are correct.

Run:

dotnet tool restore
dotnet workload install wasm-tools maui aspire

Recommended IDEs:

• Rider
• Visual Studio Code

Building Server + Web App

First, get Google Cloud credentials (key.json file) to make sure you can use Google Transcribe APIs. Copy the provided file to ~/.gcp/key.json and ensure GOOGLE_APPLICATION_CREDENTIALS env. variable stores its path.

To build & run the project:

# Start Docker containers for NGINX, PostgreSQL, Redis etc.
./docker-start.cmd

# Install dependencies and run watch (dotnet watch + webpack watch)
./run-build.cmd restore-tools npm-install watch

If you're getting RpcException with "Request had invalid authentication credentials." message, make sure your time & time zone settings are correct.

Other useful commands:

# What else build project can do?
./run-build.cmd --help

# List all available targets (you can combine them)
./run-build.cmd --list-targets

# Run with observability services (opentelemetry collector + jaeger) locally:
docker-compose -f docker-compose.observability.yml -f docker-compose.yml up

# Use either env. var or the matching option in your appsettings.local.json
$env:HostSettings__OpenTelemetryEndpoint="localhost"
./run-build.cmd watch

You can add your own targets (as C# code) to ./build/Program.cs, which is actually a Bullseye build project written in C#.

It's also useful to have an alias to run build system (to run commands like bs watch).

There are some shortcuts in *.cmd files, you can use them too.

Possible issues:

• If you use Windows, project build could break with a message about some resource related to AdamE.Firebase.iOS.Analytics package is not found. The issue is because of well-known default 260 characters limitation on the path length. Fortunately, there is a workaround to make it working.

Accessing Web App

NGINX (which runs in Docker) is configured to serve the app + its assets from https://local.actual.chat, which means you need to setup a few extra things to access it.

Setting up https://local.actual.chat

Run:

./add-hosts.cmd

Alternatively, you hosts and trust certificate manually:

• Add this line with aliases to Hosts file.

   127.0.0.1  local.actual.chat media.local.actual.chat cdn.local.actual.chat

  • Import local.actual.chat.crt to "Trusted Root Certification Authorities". You can do it with Microsoft Management Console or Chrome.

Building Mobile and Desktop Apps

The instructions below imply you're on Windows.

Windows app

• Install sign_app.cer to "Trusted Root Certification Authorities" (required only once).
• Enable Developer mode in windows settings. https://learn.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development
• Build solution:
  • using any IDE, or:
  • run msbuild from repo root, or,
  • run dotnet build from repo root.
• Run this command from repo root:

  dotnet publish src/dotnet/App.Maui/App.Maui.csproj -f net8.0-windows10.0.22000.0 -c Debug-MAUI --no-restore -p:GenerateAppxPackageOnBuild=true -p:AppxPackageSigningEnabled=true -p:PackageCertificateThumbprint=0BFF799D82CC03E61A65584D31D800924149453A

Possible issues:

• "artefacts\obj\ClientApp\project.assets.json' doesn't have a target for 'net7.0-windows10.0.22000.0" error: try to build everything in IDE and run dotnet publish with --no-restore.

Android app

TODO: write this section.

Conventions

We use:

• Conventional commits
• Standard .NET naming & style guidelines. Exceptions:
  • Place { on the same line for if, for, and any other code inside method body
  • If you have to wrap a method body expression, wrap it before => rather than after
  • A bunch of other things, see #coding-style Discord channel

Releases

We use Nerdbank.GitVersioning.

To publish a new release, run these commands from repo root:

dotnet nbgv prepare-release
# Push newly created version XX:
git push --set-upstream origin release/v0.XX

Note that release deployment won't happen unless approved by one of our core team members.

We use the alpha suffix in the master branch, beta,rc-* in release branches. When a release branch drops the version suffix it becomes a production release.