api.discord.sh

This is the backend server for discord.sh, a discord topsite created by KBVE.

Based on the template Docker Express Typescript Boilerplate by sidhantpanda with the following features:

Github Actions Workflows - Pre-configured Github Actions to run automated builds and publish image to Github Packages
Dockerfile - Dockerfile to generate docker builds.
docker-compose - Docker compose script to start service in production mode.
Containerized Mongo for development - Starts a local mongo container with data persistence across runs.
Safe Mongooose Connection Helper - A helper class to connect with Mongoose reliably.
Joi - For declarative payload validation
Middleware for easier async/await - Catches errors from routes and throws them to express error handler to prevent app crash due to uncaught errors.
OpenAPI 3.0 Spec - A starter template to get started with API documentation using OpenAPI 3.0. This API spec is also available when running the development server at http://localhost:3000/dev/api-docs
.env file for configuration - Change server config like app port, mongo url etc
Winston Logger - Uses winston as the logger for the application.
ESLINT - ESLINT is configured for linting.
Jest - Using Jest for running test cases

I. Installation

1. Clone this repo

$ git clone git@github.com:kbve/api.discord.sh.git your-app-name
$ cd your-app-name

2. Install dependencies

$ yarn install

II. Configuration

Update Docker repository for actions

$ yarn setup-actions

III. Development

Start dev server

Starting the dev server also starts MongoDB as a service in a docker container using the compose script at docker-compose.dev.yml.

$ yarn dev

Running the above commands results in

🌏API Server running at http://localhost:3000
⚙️Swagger UI at http://localhost:3000/dev/api-docs
🛢️MongoDB running at mongodb://localhost:27017

IV. Packaging and Deployment

The mongo container is only only available in dev environment. When you build and deploy the docker image, be sure to provide the correct environment variables.

1. Build and run without Docker

$ yarn build && yarn start

2. Run with docker

$ docker build -t api-server .
$ docker run -t -i \
      --env NODE_ENV=production \
      --env MONGO_URL=mongodb://host.docker.internal:27017/books \
      -p 3000:3000 \
      api-server

3. Run with docker-compose

$ docker-compose up

Environment

To edit environment variables, create a file with name .env and copy the contents from .env.default to start with.

Var Name	Type	Default	Description
NODE_ENV	string	`development`	API runtime environment. eg: `staging`
PORT	number	`3000`	Port to run the API server on
MONGO_URL	string	`mongodb://localhost:27017/books`	URL for MongoDB

Logging

The application uses winston as the default logger. The configuration file is at src/logger.ts.

All logs are saved in ./logs directory and at /logs in the docker container.
The docker-compose file has a volume attached to container to expose host directory to the container for writing logs.
Console messages are prettified
Each line in error log file is a stringified JSON.

Directory Structure

+-- scripts
|   +-- dev.sh
|   +-- setup-github-actions.sh
+-- src
|   +-- controllers
|   |   +-- book
|   |   |   +-- add.ts
|   |   |   +-- all.ts
|   |   |   +-- get.ts
|   |   |   +-- index.ts
|   |   |   +-- remove.ts
|   |   |   +-- search.ts
|   +-- errors
|   |   +-- application-error.ts
|   |   +-- bad-request.ts
|   +-- lib
|   |   +-- safe-mongo-connection.ts
|   |   +-- winston-console-transport.ts
|   +-- middleware
|   |   +-- request-middleware.ts
|   +-- models
|   |   +-- Book.ts
|   +-- public
|   |   +-- index.html
|   +-- app.ts
|   +-- logger.ts
|   +-- routes.ts
|   +-- server.ts
+-- .env.default
+-- .eslintrc.json
+-- .gitignore
+-- .gitpod.yml
+-- docker-compose.dev.yml
+-- docker-compose.yml
+-- Dockerfile
+-- jest.config.js
+-- LICENSE
+-- nodemon.json
+-- openapi.json
+-- package.json
+-- README.md
+-- renovate.json
+-- tsconfig.json
+-- yarn.lock

KBVE/api.discord.sh