Merge remote-tracking branch 'origin/master'

README.md

@@ -1,2 +1,68 @@
 # kittyBE
+*Back-end for the [KittyURL](https://gitea.7o7.cx/kittyteam/kittyurl) project -- create short and memorable URLs with ease!*
 
+## Goals
+Provide endpoints for:
+- account management (`/api/v1/user/*`),
+- link management (`/api/v1/link/*`),
+- authed link management (when a link is bound to a user, `/api/v1/authed/*`),
+- user management (for admins only, `/api/v1/admin/*`),
+- general info (`/api/v1/info/*`),
+
+KittyBE should also integrate nicely with [kittyFE](https://gitea.7o7.cx/kittyteam/kittyFE) and be easily dockerizable.
+
+## Running kittyBE
+KittyURL has been verified to work on Node 18.20+ and PostgreSQL 16.11+.
+### On bare metal
+Running the back-end is as simple as:
+
+- Installing the dependencies:
+	- To just download the required dependencies:
+		```sh
+		npm i
+		```
+	- To install an exact copy of all of the dependencies:
+		```sh
+		npm ci
+		```
+- Copying the .env.default file to .env, and customizing it to own preferences.
+	**Example:** Say, you want to add a domain to the trusted CORS origins list. To do so, your .env file in your editor of choice and append a comma (`,`) with the origin you want to add (say, `http://example.com`). Your .env file might then look as follows: `TRUSTED_ORIGINS=http://localhost:6568,http://example.com`.
+	**Important:** Make sure to change the `ACCESS_TOKEN_PRIVATE_KEY` variable to something secure, as this secret value will be used to generate user sessions. **Setting a weak key will allow attackers to potentially bruteforce your secret and forge user tokens!**
+- Pasting your wordlist file into `src/tools/wordlist.ts`.
+	No wordlist file exists by default in `src/tools/wordlist.ts`. This is because wordlists were meant to be as modular as possible (with the philosophy of "bring your own wordlist"). If you leave that as-is, you'll run into runtime errors.
+	However, if you don't want to provide your own wordlist, and just want to get up and running as fast as possible, you're free to use the provided sample `wordlist.example-large.ts` file. Just copy it into `src/tools/wordlist.ts`:
+	```sh
+	cp wordlist.example-large.ts src/tools/wordlist.ts
+	```
+- Launching the web server:
+	```sh
+	npm start
+	```
+- And... that's it!
+	Now view your instance at http://localhost:6567, and -- if you've set the DEBUG flag in your `.env` file to `true` -- you can also visit http://localhost:6567/kttydocs/ for Swagger documentation.
+
+### Using Docker
+A Docker image is built for every release of kittyBE and [kittyFE](https://gitea.7o7.cx/kittyteam/kittyFE). For more instructions on how to run the project with Docker, please refer to the [kittyurl repository](https://gitea.7o7.cx/kittyteam/kittyurl) (which contains a sample [docker-compose.yaml file](https://gitea.7o7.cx/kittyteam/kittyurl/src/branch/master/docker-compose.yaml), as well as it's own .env file).
+
+## Wordlists
+You're free to provide your own wordlist file by pasting it into `src/tools/wordlist.ts`. For an example of how a wordlist file should look like, see `wordlist.example-large.ts`, and pay attention to the methods it exports.
+
+## Troubleshooting
+Two supplementary scripts have been provided for aid in troubleshooting database-related errors.
+- Run pending migrations on your database
+	In a rare case, when you need to run the migrations before launching the server (as it will try running pending migrations on every launch), use:
+	```sh
+	npm run pendingMigration
+	```
+
+- Issue a new migration
+	During development it might be necessary to issue new migrations. To do that, use:
+	```sh
+	# assuming you're in the base project directory
+	npm run newMigration ./src/migrations/myMigrationName
+	```
+	where `myMigrationName` is the name of your migration.
+
+	**Important:** TypeORM uses the state of your connected database when diffing for changes, unlike some other solutions, which take past migrations into consideration.
+
+**Note:** If using other relational database than Postgres, make sure to do the due diligence of researching how to enable bigint support for your database driver. No other database type than Postgres has been tested.