aboutsummaryrefslogtreecommitdiffhomepage
path: root/support/doc/development/server.md
diff options
context:
space:
mode:
Diffstat (limited to 'support/doc/development/server.md')
-rw-r--r--support/doc/development/server.md74
1 files changed, 74 insertions, 0 deletions
diff --git a/support/doc/development/server.md b/support/doc/development/server.md
new file mode 100644
index 000000000..4647f2b4f
--- /dev/null
+++ b/support/doc/development/server.md
@@ -0,0 +1,74 @@
1# Server code
2
3## Add a new feature walkthrough
4
5Here's a list of all the parts of the server to update if you want to add a new feature (new API REST endpoints for example) to the PeerTube server.
6Some of these may be optional (for example your new endpoint may not need to send notifications) but this guide tries to be exhaustive.
7
8 * Configuration:
9 - Add you new configuration key in `config/default.yaml` and `config/production.yaml`
10 - If you configuration needs to be different in dev or tests environments, also update `config/dev.yaml` and `config/test.yaml`
11 - Load your configuration in `server/initializers/config.ts`
12 - Check new configuration keys are set in `server/initializers/checker-before-init.ts`
13 - You can also ensure configuration consistency in `server/initializers/checker-after-init.ts`
14 - If you want your configuration to be available in the client:
15 + Add your field in `shared/models/server/server-config.model.ts`
16 + Update `server/lib/server-config-manager.ts` to include your new configuration
17 - If you want your configuration to be updatable by the web admin in the client:
18 + Add your field in `shared/models/server/custom-config.model.ts`
19 + Add the configuration to the config object in the `server/controllers/api/config.ts` controller
20 * Controllers:
21 - Create the controller file and fill it with your REST API routes
22 - Import and use your controller in the parent controller
23 * Middlewares:
24 - Create your validator middleware in `server/middlewares/validators` that will be used by your controllers
25 - Add your new middleware file `server/middlewares/validators/index.ts` so it's easier to import
26 - Create the entry in `server/types/express.d.ts` to attach the database model loaded by your middleware to the express response
27 * Validators:
28 - Create your validators that will be used by your middlewares in `server/helpers/custom-validators`
29 * Typescript models:
30 - Create the API models (request parameters or response) in `shared/models`
31 - Add your models in `index.ts` of current directory to facilitate the imports
32 * Sequelize model (BDD):
33 - If you need to create a new table:
34 + Create the Sequelize model in `server/models/`:
35 * Create the `@Column`
36 * Add some indexes if you need
37 * Create static methods to load a specific from the database `loadBy...`
38 * Create static methods to load a list of models from the database `listBy...`
39 * Create the instance method `toFormattedJSON` that creates the JSON to send to the REST API from the model
40 + Add your new Sequelize model to `server/initializers/database.ts`
41 + Create a new file in `server/types` to define multiple versions of your Sequelize model depending on database associations
42 + Add this new file to `server/types/*/index.ts` to facilitate the imports
43 + Create database migrations:
44 * Create the migration file in `server/initializers/migrations` using raw SQL (copy the same SQL query as at PeerTube startup)
45 * Update `LAST_MIGRATION_VERSION` in `server/initializers/constants.ts`
46 - If updating database schema (adding/removing/renaming a column):
47 + Update the sequelize models in `server/models/`
48 + Add migrations:
49 * Create the migration file in `initializers/migrations` using Sequelize Query Interface (`.addColumn`, `.dropTable`, `.changeColumn`)
50 * Update `LAST_MIGRATION_VERSION` in `server/initializers/constants.ts`
51 * Notifications:
52 - Create the new notification model in `shared/models/users/user-notification.model.ts`
53 - Create the notification logic in `server/lib/notifier/shared`:
54 + Email subject has a common prefix (defined by the admin in PeerTube configuration)
55 - Add your notification to `server/lib/notifier/notifier.ts`
56 - Create the email template in `server/lib/emails`:
57 + A text version is automatically generated from the HTML
58 + The template usually extends `../common/grettings` that already says "Hi" and "Cheers". You just have to write the title and the content blocks that will be inserted in the appropriate places in the HTML template
59 - If you need to associate a new table with `userNotification`:
60 + Associate the new table in `UserNotificationModel` (don't forget the index)
61 + Add the object property in the API model definition (`shared/models/users/user-notification.model.ts`)
62 + Add the object in `UserNotificationModel.toFormattedJSON`
63 + Handle this new notification type in client (`UserNotificationsComponent`)
64 + Handle the new object property in client model (`UserNotification`)
65 * Tests:
66 - Create your command class in `shared/server-commands/` that will wrap HTTP requests to your new endpoint
67 - Add your command file in `index.ts` of current directory
68 - Instantiate your command class in `shared/server-commands/server/server.ts`
69 - Create your test file in `server/tests/api/check-params` to test middleware validators/authentification/user rights (offensive tests)
70 - Add it to `server/tests/api/check-params/index.ts`
71 - Create your test file in `server/tests/api` to test your new endpoints
72 - Add it to `index.ts` of current directory
73 - Add your notification test in `server/tests/api/notifications`
74 * Update REST API documentation in `support/doc/api/openapi.yaml`