You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This repository presents a backend boilerplate based on [NestJS](https://github.com/nestjs/nest) and [Hasura](https://hasura.io) with some [features](#features).
12
+
This repository presents a backend boilerplate based on [NestJS](https://github.com/nestjs/nest) and [Hasura](https://hasura.io) with some [features](#features). Of course there are many templates you can use, but this boilerplate allows developers to construct a backend system with light and intuitive skills. Therefore, it may not have the highest level of skills, but it may be an easier way to experience backend systems.
13
13
14
-
Of course there are many templates you can use, but this boilerplate allows beginners to construct the backend without difficult skills. Thus, it may not have the highest level of skills, but it may be an easier way to experience.
14
+
In this boilerplate, a backend system will consist of NestJS, Hasura, and Postgres. You can find out descriptions about them in [overview](./docs/1.overview.md).
15
15
16
-
_You can start, implement, and deploy your backend server easily with this boilerplate._
16
+
_**You can start, implement, and deploy your backend system easily with this boilerplate.**_
17
17
18
-
## NestJS + Hasura + Postgres = Backend
18
+
## 🥅 Goals
19
19
20
-
Even if you are new to the backend, you may know that the backend starts with a system of servers and databases. This repository is aimed at that point.
21
-
22
-
A basic backend system can be started with NestJS, Hasura, and Postgres. You can enjoy the convenience of sending/receiving data by preparing the Postgres database, implementing the NestJS server, and connecting the Hasura server.
23
-
24
-
Here are some descriptions for them used in this boilerplate.
25
-
26
-
### [NestJS](https://github.com/nestjs/nest)
27
-
28
-
Nest is the TypeScript framework to implement server based on Node.js, and it contains a lot of features, such as OOP (Object Oriented Programming), FP (Functional Programming), and so on.
29
-
30
-
- You can use this to handle data (domain) or to implement and execute business logics.
31
-
32
-
### [Hasura](https://hasura.io)
33
-
34
-
Hasura is the GraphQL engine with a database management system, which includes functions that perform the tasks the server needs to do instead. In simple way, it is basically similar to a database administrator system, but as a proxy server, it has functions such as Relaying, Batch, and authentication, and of course supports GraphQL functionality for databases.
35
-
36
-
- You can use this to manage/monitor databases, authenticate, and reduce the workload of the server implementation.
37
-
38
-
### [Postgres](https://www.postgresql.org/)
20
+
This boilerplate aims to:
39
21
40
-
Postgres is an open-source relational database system (In fact, you can use another database system such like MySQL for your purposes).
22
+
-**Productivity** : Start new projects quickly and configure your environments
23
+
-**Education** : Adaption of NestJS and Hasura usages
24
+
-**Utilization** : Testing for new code or library easily
41
25
42
-
However, this has affinity with NestJS and Hasura, and is an advanced database system that is highly recommended because it has many advantages, including ACID compatibility, JSON and JSONB type support, and support for various advanced functions.
26
+
Among them, we are most focused on **productivity**. For productivity, you will construct the following backend system:
43
27
44
-
- You can use this as a database. That is all.
28
+
1._Postgres_, _NestJS_, and _Hasura_ are running on _Docker_ container that they are started by simple shell scripts with some commands.
45
29
46
-
# Goals
30
+
2. All client requests are made through _Hasura_.
31
+
3. GraphQL queries are mainly used in client data requests that are automatically generated by _Hasura_.
32
+
4. All permissions for data requests are set in _Hasura_.
33
+
5. Business logic functions are implemented in _NestJS_ server, and registered as _Hasura Actions_.
34
+
6. Permissions for business logic functions are double set in _Hasura_ and _NestJS_ server.
47
35
48
-
## Not RESTful, but Hasura-ful
49
-
50
-
This boilerplate aims to:
51
-
52
-
-**Productivity** : Start new projects quickly and configure your environment
53
-
-**Education** : Adaption of NestJS and Hasura usage
54
-
-**Utilization** : Testing for new code or library easily
55
-
56
-
In this version, we are most focused on **productivity**.
36
+
Moreover, this _NestJS_ boilerplate has **monolithic architecture** to aim for productivity.
57
37
58
38
> _In various backend architectures, DDD (Domain-driven design) or micro-service nature may be more useful. However, we aimed to incorporate the advantages of Hasura into NestJS. Therefore, we tried to increase the productivity of the backend by focusing on implementing Action Handler (Hasura feature) in NestJS._
59
39
60
-
# Summary
40
+
## 📝 Summary
41
+
42
+
> _This summary is like a kind of technical stack covered by this boilerplate._
@@ -66,12 +48,13 @@ In this version, we are most focused on **productivity**.
66
48
| Package Manager | yarn |
67
49
| Architecture | Monolith, CQRS |
68
50
| Documentation | Swagger |
69
-
| Database | TypeORM & Postgres |
70
-
| DB Admin | Hasura |
51
+
| ORM | TypeORM |
52
+
| Database | Postgres |
53
+
| GraphQL Engine | Hasura |
71
54
| Interaction | Hasura Query & Actions |
72
55
| Deployment | Dockerlized |
73
56
74
-
# Features
57
+
## 😎 Features
75
58
76
59
-[x] Architecture from CQRS Pattern (focusing on Hasura Action Handler)
77
60
-[x] Focusing on Code Sharing for Collaboration
@@ -83,83 +66,49 @@ In this version, we are most focused on **productivity**.
83
66
-[x] User/Auth Examples
84
67
-[x] Docker Versioning and Deployment
85
68
86
-
# Start
87
-
88
-
## Prerequisites
89
-
90
-
The infrastructures, Postgres and Hasura, run on top of docker container by `docker-compose` command in this boilerplate. If you already ran those infrastructures, you do not need to follow this step. However, you should note that Hasura requires JWT settings.
91
-
92
-
You can install docker as [desktop-app](https://docs.docker.com/get-docker/) or [engine](https://docs.docker.com/engine/install/). After installation, `docker-compose` may be installed together. If not, install it using the [command](#docker-compose).
93
-
94
-
We shares some commands to install `docker-compose`. Note that the below commands are executed in Ubuntu 18.04:
95
-
96
-
### Ready to install docker
97
-
98
-
Update apt package index and install packages to use the repository via HTTPs:
$(lsb_release -cs) stable"| sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
113
-
```
71
+
### 1. Prerequisites
114
72
115
-
### Docker
73
+
> _If you already have Docker engine and `docker-compose` command, skip this step._
116
74
117
-
Install docker engine with the latest version:
75
+
We need `docker` and `docker-compose` commands to run the servers. The servers are running on docker containers by our shell scripts with the commands.
118
76
119
-
```bash
120
-
$ sudo apt-get update # Essential to install 'docker-ce'
$ sudo chmod 666 /var/run/docker.sock # If got permission denied to docker daemon socket
123
-
```
77
+
You can install docker as [desktop-app](https://docs.docker.com/get-docker/) or [engine](https://docs.docker.com/engine/install/). We share some commands to install docker in [prerequisites document](./docs/2.prerequisites.md). After docker installation, `docker-compose` command may be installed together. If not, use the command in the document to install.
124
78
125
-
### Docker-compose
79
+
### 2. Cloning
126
80
127
-
Install docker-compose:
81
+
Clone this repository:
128
82
129
83
```bash
130
-
$ sudo curl -L "https://github.com/docker/compose/releases/download/1.24.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose # '1.24.0' can be replaced with a specific version
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
89
+
You should prepare settings to start Postgres, Hasura, and NestJS server. The settings are set in _`.env`_ environment variable files. You can find an example of those files in each directory of them.
139
90
140
-
$ docker-compose --version
141
-
docker-compose version 1.17.1, build unknown
142
-
```
91
+
#### 3.1 JWT Setting
143
92
144
-
## Cloning
93
+
In this boilerplate, JWT authentication is applied to control user accesses. NestJS server will issue access tokens, and Hasura server will verify the tokens at the forefront of client requests. Therefore, the public key of JWT must be registered in Hasura. Use this command to generate a new JWT key pair:
A new RSA key pair will be printed in your console. Copy them to set in Hasura and NestJS servers.
151
100
152
-
You should prepare settings to start Postgres, Hasura, and NestJS server. The settings are set in _`.env`_ environment variable files.
101
+
### 4. Run Infrastructures
153
102
154
-
### Postgres
103
+
#### 4.1. Run Postgres
155
104
156
-
Follow this [document](./postgres/README.md) in Postgres directory.
105
+
Follow steps of [document](./postgres/README.md) in Postgres directory. Since the run of Postgres does not have much difficulty, it simply needs to be completed to run a database.
157
106
158
-
### Hasura
107
+
#### 4.2. Run Hasura
159
108
160
-
Follow this [document](./hasura/README.md) in Hasura directory.
109
+
Follow steps of [document](./hasura/README.md) in Hasura directory. Note that JWT public key generated in [settings](#31-jwt-setting) must be set in Hasura setting.
161
110
162
-
### NestJS boilerplate
111
+
### 5. Run NestJS boilerplate
163
112
164
113
See _`.env.example`_ file in root directory, and copy it as _`.env`_ file to set environment variables.
165
114
@@ -170,13 +119,13 @@ See _`.env.example`_ file in root directory, and copy it as _`.env`_ file to set
Even if you are new to the backend, you may know that the backend starts with a system of servers and databases. We help to develop to that level.
6
+
7
+
A basic backend system can be started with NestJS, Hasura, and Postgres. _Postgres_ is a database to save persistent data, _Hasura_ is a relaying server with query support, and _NestJS_ is an implementing server with business logics.
8
+
9
+
Here are some descriptions for them used in this boilerplate.
10
+
11
+
## Backend = NestJS + Hasura + Postgres
12
+
13
+
### NestJS
14
+
15
+
Nest is the TypeScript framework to implement server based on Node.js, and it contains a lot of features, such as OOP (Object Oriented Programming), FP (Functional Programming), and so on.
16
+
17
+
> _Please see the [official documents](https://nestjs.com/) to know about NestJS._
18
+
19
+
In this boilerplate:
20
+
21
+
- Nest server is basically an API server, but it serves as a webhook server of Hasura.
22
+
- Nest server handles your data domain and execute main business logics.
23
+
- Nest server is responsible for controlling user permissions, such as validating and issuing access tokens.
24
+
- Nest server is responsible for executing command(creation, update, and deletion) data according to business logic (it corresponds to 'Mutation' in GraphQL).
25
+
26
+
### Hasura
27
+
28
+
Hasura is a GraphQL engine with database management system, which includes functions that perform the tasks the server needs to do instead. In simple way, it is basically similar to a database administrator system, but as a relaying server, it has functions such as ACTIONS(Webhook), EVENTS(Batch), and User-Permissions(authentication), and of course supports GraphQL functionality for databases.
29
+
30
+
> _Please see the [official documents](https://hasura.io/docs/latest/index/) to know about Hasura._
31
+
32
+
In this boilerplate:
33
+
34
+
- Hasura is a GraphQL Engine that automatically generates basic CRUD(Query/Mutation) by connecting to databases.
35
+
- Hasura is a database management system that can monitor and manage the database connected.
36
+
- Hasura is a closer server to clients than Nest server, thus, the clients send a request to Hasura.
37
+
- Hasura registers webhook handlers of Nest server, enabling them to run as GraphQL mutation through ACTIONS.
38
+
- Hasura validates permissions to use query and mutation to control users with verification of the access token issued by Nest server.
39
+
40
+
### Postgres
41
+
42
+
Postgres is an open-source relational database system. In fact, you can use another database system such like MySQL for your purposes, however, Postgres has affinity with NestJS and Hasura at variable examples and supports. Moreover, it is an advanced database system that has many advantages, including ACID compatibility, JSON and JSONB type support, and support for various advanced functions.
43
+
44
+
> _Please see the [official documents](https://www.postgresql.org/docs/) to know about Postgres._
45
+
46
+
In this boilerplate:
47
+
48
+
- Postgres is a database to save data.
49
+
- Nest server connects to Postgres database to query and change data.
50
+
- Hasura connects to Postgres database to query and monitor data.
$ sudo chmod 666 /var/run/docker.sock # If got permission denied to docker daemon socket
32
+
```
33
+
34
+
## Docker-compose
35
+
36
+
Install docker-compose:
37
+
38
+
```bash
39
+
$ sudo curl -L "https://github.com/docker/compose/releases/download/1.24.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose # '1.24.0' can be replaced with a specific version
40
+
$ docker-compose version
41
+
```
42
+
43
+
Now check that docker with compose is available:
44
+
45
+
```bash
46
+
$ docker ps
47
+
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
0 commit comments