plc.jbc.lol
A modified version of Wafrn used on https://wf.jbc.lol (mirror of https://git.jbc.lol/jbcrn/wf.jbc.lol which is a mirror of https://codeberg.org/jbcarreon123/wf.jbc.lol)
1# Developing wafrn
2
3## Project Structure
4
5Wafrn is split between an [Angular](https://angular.dev) frontend and a [NodeJS](https://nodejs.org/en) backend.
6
7```text
8packages/
9├── frontend/
10│ ├── routes/
11│ ├── util/
12│ ├── README.md
13│ └── ...
14└── backend/
15 ├── src/
16 │ ├── app/
17 │ ├── assets/
18 │ └── ...
19 ├── README.md
20 └── ...
21```
22
23(Tree made with [tree.nathanfriend.io](https://tree.nathanfriend.io/))
24
25## Contributing
26
27If you would like to help develop the Frontend or Backend, read the README.md of the respective package.
28
29- [Frontend - README.md](../packages/frontend/README.md)
30- [Backend - README.md](../packages/backend/README.md)
31
32## Local setup pointing to the production frontend
33
34If 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:
35
361. Clone the repo
372. Install node 24 or use the provided Nix shell script
383. Run `npm install` at the root of the project
394. Run `npm run frontend:develop:prod`
40
41If you want to point to a different backend or see additional information on the nix shells script, see the Frontend README file.
42
43## Local setup with a local dummy instance
44
45If 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](../packages/frontend/README.md) for more details
46
47If 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:
48
491. Run `./install/env_local_setup.sh`. This will setup the backend and frontend environment files to point to each other locally.
50
512. Run `docker compose up`. This will start up the required services: PostgreSQL, Redis and Caddy
52
53> **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.
54
55> **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.
56
573. Set up the the backend:
58
59```sh
60cd packages/backend
61npm i
62npm run db:migrate
63```
64
654. Set up the frontend:
66
67```sh
68cd packages/frontend
69npm i
70npm exec -- ng build --configuration=devlocal
71```
72
735. Start backend & frontend
74
75```sh
76cd packages/backend
77NODE_TLS_REJECT_UNAUTHORIZED=0 npm start
78```
79
80```sh
81cd packages/frontend
82npm exec -- ng serve --host 0.0.0.0 --configuration=devlocal
83```
84
856. If all is well go to `https://localhost` to see your app
86
87The default username/password for local installation is: `admin@example.com` / `Password1!`
88
89> **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.
90
91> **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](./deployment.md) as a staging server if you wish to develop features that require proper access to the Fediverse and/or Bluesky
92
93## Fullstack development with debugger
94
95Ok 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!
96
971. Clone the repo
982. Install docker and node 24
993. Do this command on the root of the project `npm install`
1004. Copy the docker compose for local development `cp docker-compose.localBackendDebuggerDev.yml docker-compose.yml`
1015. Copy the development environment file for backend `cp packages/backend/environment.dev.ts packages/backend/environment.ts`
1026. 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`
1037. Check that you can connect to the database in your browser in https://localhost:8080 . If you have problem here, contact the dev team
1048. Edit the environment file. Replace adminEmail and adminUser with your desired email, user and password. Use this file as a template, check for the EDIT HERE comments:
105
106```import { Environment } from './interfaces/environment.js'
107
108export const baseEnvironment: Environment = {
109 prod: false,
110 // this makes the logs really heavy, but might be useful for queries
111 logSQLQueries: true,
112 workers: {
113 // if you set this to true, workers will start in the main thread. no need for starting the utils/workers.ts in other tmux tab
114 mainThread: true,
115 low: 5,
116 medium: 10,
117 high: 100
118 },
119 // this was a dev thing. leave to true unless you are doing stuff in local or your media url is yourinstance/uploads (not recomended)
120 removeFolderNameFromFileUploads: true,
121 // we use now postgresql.
122 databaseConnectionString: 'postgresql://root:root@localhost:5432/wafrn',
123 // PROD
124 // databaseConnectionString: 'postgresql://wafrn:Skied-Obscurity6-Tightwad@localhost:1111/wafrn',
125
126 listenIp: '0.0.0.0',
127 port: 3002,
128 // In the case of you wantint to put fedi petitions in another thread, use a different port here. You will have to update your apache config
129 fediPort: 3002,
130 // If you want to run the cache routes in another port, same thing!
131 cachePort: 3002,
132 saltRounds: 14,
133 // for jwt secret you should use something like https://www.grc.com/passwords.htm please this is SUPER DUPER SECRET.
134 jwtSecret: Buffer.from('secret', 'base64'),
135 // https://app.wafrn.net
136 // EDIT HERE if you are gona do fedi stuff like ssh -R 192.168.100.100:3002:localhost:3002 192.168.100.100
137 frontendUrl: 'https://instance3.dev.wafrn.net',
138 // app.wafrn.net
139 // EDIT HERE (optional)
140 instanceUrl: 'instance3.dev.wafrn.net',
141 // https://media.wafrn.net
142 mediaUrl: 'https://local.dev.wafrn.net/api/uploads',
143 // You should run also this project github.com/gabboman/fediversemediacacher. In my case, https://cache.wafrn.net/?media= The cache is there because at some point in the past I configured it to precache images. No need for it to be honest
144 externalCacheurl: 'https://local.dev.wafrn.net/api/cache?media=',
145 // If main cache fails due to IP limits you can install additional proxies, and use them here. The cache will try these as well before failing.
146 // You can deploy https://github.com/sztupy/did-decoder-lambda this project to Netlify or Vercel as a backup for example
147 externalCacheBackups: [],
148 // after the first run, create the admin user. and a deleted user. You will have to edit the user url in db so it starts with an @
149 adminUser: 'admin',
150 // admin email wich you will recive things like "someone registred and you need to review this"
151 // EDIT HERE
152 adminEmail: 'YOUREMAILGOESHERE',
153 adminPassword: 'ADMINPASSWORD',
154 // after creating the deleted_user we advice to also set the user to BANNED
155 deletedUser: '@DELETEDUSER',
156 // in MB. Please make sure you have the same in the frontend
157 uploadLimit: 250,
158 // 20 is a good number. With the new query we could investigate a higher number but no need to do it
159 postsPerPage: 20,
160 // trace is extreme logging. debug is ok for now
161 logLevel: 'debug',
162 // There is a script that loads the file from this url and blocks the servers
163 blocklistUrl: '',
164 // In some cases we serve the frontend with the backend with a small preprocessing. We need the location of the frontend
165 // EDIT HERE: put a location with a build of the frontend. or an index file. you may need this
166 frontedLocation: '/Users/gabriel/workspace/wafrn/packages/frontend/dist/wafrn/browser',
167 // oh yes, you need TWO redis connections, one for queues other for cache
168 bullmqConnection: {
169 host: 'localhost',
170 port: 6379,
171 db: 0
172 },
173 // second database used for cache
174 redisioConnection: {
175 host: 'localhost',
176 port: 6379,
177 db: 1
178 },
179 // this will create a backendlog.log file on the folder superior to this one.
180 pinoTransportOptions: {
181 targets: [
182 {
183 target: 'pino/file',
184 level: 'trace',
185 options: {
186 destination: 1
187 }
188 }
189 ]
190 },
191 // you can try with gmail but we actually use sendinblue for this. bear in mind that this might require some fiddling in your gmail account too
192 // you might need to enable https://myaccount.google.com/lesssecureapps
193 // https://miracleio.me/snippets/use-gmail-with-nodemailer/
194 emailConfig: {
195 host: 'mail.wafrn.net',
196 port: 587,
197 auth: {
198 user: 'info@wafrn.net',
199 pass: 'didYouThoughtIwouldLeaveThisOneHere?',
200 from: 'info@wafrn.net'
201 }
202 },
203 // you dont have an smtp server and you want to do a single user instance? set this to true!
204 disableRequireSendEmail: true,
205 // if someone is trying to scrap your place you can send a funny message in some petitions (attacks to the frontend)
206 blockedIps: [] as string[],
207 // do you want to manually review registrations or have them open? We advice to leave this one to true
208 reviewRegistrations: true,
209 // if the blocklist youre using turns out to be biased you can tell the script that loads the block host to do not block these hosts
210 ignoreBlockHosts: [] as string[],
211 // default SEO data that will be used when trying to load server data
212 defaultSEOData: {
213 title: 'localhost',
214 description: 'localhost, a wafrn instance',
215 img: 'https://localhost/assets/logo.png'
216 },
217 // EDIT HERE if you have a PDS that you want to connect
218 enableBsky: false,
219 bskyPds: 'at.app.wafrn.net',
220 bskyPdsJwtSecret: 'SECRET1',
221 bskyPdsAdminPassword: 'SECRET2',
222 // to generate these keys use the following command: `npx web-push generate-vapid-keys`.
223 webpushPrivateKey: 'CDUUngHrbAUOBg_1-jXZJFj3IOGMTAbR5zhJupKzMOE', // dont worry these ones are local
224 webpushPublicKey: 'BIWrO9knKAnPj2TFfU7pIxo0QkO_b2-PZCqYwAPArJdHTQ3Xsvf-E_WXaKGFB531fBOxCE92SZ6R_vHTVM1yTNw',
225 // this is a email that will be sent to the distribution services in the users devices in case the owner of the distribution service wants to contact the server that is sending the notifications
226 webpushEmail: 'mailto:info@wafrn.net',
227 frontendEnvironment: {
228 logo: '/assets/logo.png',
229 frontUrl: 'http://localhost:4200',
230 baseUrl: 'http://localhost:4200/api',
231 baseMediaUrl: '/api/uploads',
232 externalCacheurl: '/api/cache?media=',
233 shortenPosts: 3,
234 disablePWA: false,
235 maintenance: false
236 }
237}
238```
239
2409. Do this command to initialize the database `cd packages/backend && npm run db:migrate`
24110. On the root directory, do this command to start the backend server: `npm run backend:develop`
24211. Do this command to start the frontend `npm run frontend:develop:prod`
24312. Enjoy!
244
245### Fullstack development with fedi and bluesky access and debugger access
246
247This part of the guide needs to be written properly, BUTT, the QUICK AND DIRTY explanation for this is:
248
249Execute the steps of "Fullstack development with debugger"
250
251You will require a VPS with caddy and a bluesky PDS and a domain
252
253Update the config on environment.ts:
254You will need to update: frontendUrl, instanceUrl, mediaUrl, externalCacheurl, email things too probably (optional), and if you want buesky too: enableBsky, bskyPds, bskyPdsJwtSecret, bskyPdsAdminPassword
255
256Once you do that and have stuff runing, to listen to the bluesky pds you will also need to start the atproto listener
257
258`npm run backend:atproto`
259
260Regarding 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:
261
262`ssh -R 3002:localhost:3002 USER@YOURVPS`
263
264This will "mirror" your port 3002 to the internal port 3002 of your vps. You can reverse proxy that one.