jbc.lol / wafrn
unoffical wafrn mirror wafrn.net
atproto social-network activitypub
fork atom
wafrn / docs / development.md
at api-load-balancing 5.6 kB view raw view code
FireIsGood feat: improve wording of development readme
2b05a62d

Developing wafrn#

Project Structure#

Wafrn is split between an Angular frontend and a NodeJS backend.

packages/
├── frontend/
│   ├── routes/
│   ├── util/
│   ├── README.md
│   └── ...
└── backend/
    ├── src/
    │   ├── app/
    │   ├── assets/
    │   └── ...
    ├── README.md
    └── ...

(Tree made with tree.nathanfriend.io)

Contributing#

If you would like to help develop the Frontend or Backend, read the README.md of the respective package.

Local setup pointing to the production frontend#

If you want to do development on the frontend and what you do does not require doing something like posting a lot or spaming an external account, you can simply:

  1. Clone the repo
  2. Install node 24 or use the provided Nix shell script
  3. Run npm install at the root of the project
  4. Run npm run frontend:develop:prod

If you want to point to a different backend or see additional information on the nix shells script, see the Frontend README file.

Local setup with a local dummy instance#

If you want to develop Wafrn frontend but require to do more "noisy" stuff, you can point it at a working instance. See Frontend - README.md for more details

If you want to setup both the backend and frontend locally there are a couple of helper scripts that can help you set up a local environment:

  1. Run ./install/env_local_setup.sh. This will setup the backend and frontend environment files to point to each other locally.

  2. Run docker compose up. This will start up the required services: PostgreSQL, Redis and Caddy

Note: If you're not a fan of docker, or you already have these services running, you can also install PostgreSQL, Redis and Caddy manually.

Note: If you are running Caddy manually, or you are not using Docker Desktop but a more native docker installation, you will need to edit packages/frontend/Caddyfile and replace host.docker.internal with localhost for it to work properly.

  1. Set up the the backend:
cd packages/backend
npm i
npm run db:migrate
  1. Set up the frontend:
cd packages/frontend
npm i
npm exec -- ng build --configuration=devlocal
  1. Start backend & frontend
cd packages/backend
NODE_TLS_REJECT_UNAUTHORIZED=0 npm start

cd packages/frontend
npm exec -- ng serve --host 0.0.0.0 --configuration=devlocal
  1. If all is well go to https://localhost to see your app

The default username/password for local installation is: admin@example.com / Password1!

Note: You can run caddy trust to install Caddy's root certificates, to the system store. This will remove the security warnings from your browser. You can also do caddy untrust once you're finished with the development.

Warning: Due to how the Fediverse and Bluesky operates not all features will be accessible when developing the backend locally. You might want to host your own Wafrn instance as a staging server if you wish to develop features that require proper access to the Fediverse and/or Bluesky

Fullstack development with debugger#

Ok so you definetively need to do some backend stuff! As long as you do not need to do fedi stuff and bluesky stuff, it's easy!

  1. Clone the repo
  2. Install docker and node 24
  3. Do this command on the root of the project npm install
  4. Copy the docker compose for local development cp docker-compose.localBackendDebuggerDev.yml docker-compose.yml
  5. Copy the development environment file for backend cp packages/backend/environment.dev.ts packages/backend/environment.ts
  6. Start the services required for wafrn to work: redis, postgres, and a db admin tool on https://localhost:8080 (type postgres, user and pass: root, db: wafrn) docker compose up -d
  7. Check that you can connect to the database in your browser in https://localhost:8080 . If you have problem here, contact the dev team
  8. Edit the environment file. Replace adminEmail and adminUser with youur desired email, user and password
  9. Do this command to initialize the database cd packages/backend && npm run db:migrate
  10. On the root directory, do this command to start the backend server: npm run backend:develop
  11. Do this command to start the frontend npm run frontend:develop:prod
  12. Enjoy!

Fullstack development with fedi and bluesky access and debugger access#

This part of the guide needs to be written properly, BUTT, the QUICK AND DIRTY explanation for this is:

Execute the steps of "Fullstack development with debugger"

You will require a VPS with caddy and a bluesky PDS and a domain

Update the config on environment.ts: You will need to update: frontendUrl, instanceUrl, mediaUrl, externalCacheurl, email things too probably (optional), and if you want buesky too: enableBsky, bskyPds, bskyPdsJwtSecret, bskyPdsAdminPassword

Once you do that and have stuff runing, to listen to the bluesky pds you will also need to start the atproto listener

npm run backend:atproto

Regarding fedi, you will need to create a reverse proxy with the url of the instance pointing to your machine. What I do is that i use the vps as a jump like this:

ssh -R 3002:localhost:3002 USER@YOURVPS

This will "mirror" your port 3002 to the internal port 3002 of your vps. You can reverse proxy that one.