Skip to content

Commit 0202c71

Browse files
roschaeferroschaefer
authored
Merge pull request #12 from Human-Connection/11-update-readme-file
[WIP] Update readme file & Docker Setup
2 parents 9e4aa70 + f696847 commit 0202c71

4 files changed

Lines changed: 158 additions & 40 deletions

File tree

‎Dockerfile‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
FROM node:11
2+
3+
# Set Node environtment
4+
#ENV NODE_ENV=development
5+
6+
# Switch to working directory
7+
WORKDIR /home/node/coc-api
8+
9+
# Copy contents of local folder to `WORKDIR`
10+
COPY . .
11+
12+
# Install nodemon globally
13+
RUN npm install --global nodemon
14+
15+
# Install dependencies from package.json
16+
RUN npm install --quiet --no-warnings
17+
18+
# Expose port from container so host can access 1337
19+
EXPOSE 1337

‎README.md‎

100644100755
Lines changed: 112 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,116 @@
1-
**COC API Server**
1+
# Clock of Change - API Server (Backend)
22

3-
the new COC API is written in nodejs on top of express.
4-
All routes reside in /core/restapi.js
3+
4+
This repository contains the API Server - or in other terms Backend - of the Clock of Change.
5+
6+
To find out more about the Clock of Change and Human Connection - the network behind it - visit https://human-connection.org/en/.
7+
8+
## Tech Stack
9+
10+
* Node.js: The API Server is running on [Node.js](https://nodejs.org/en/) - a JavaScript runtime environment for server-side scripting
11+
* Express.js: We use the [Express.js](https://expressjs.com/en/) framework - a Node.js framework to help build web applications
12+
* Nodemon: We use [Nodemon](https://nodemon.io/) for development - a handy replacement wrapper for Node.js that automatically restarts the application on file changes
13+
* MySQL: We use [MySQL](https://www.mysql.com) as our relational database of choice to store our data
14+
15+
16+
## Project Structure & Components
17+
18+
**PROJECT STRUCTURE / DIRECTORIES**
19+
20+
* server.js: The starting point for this Node.js application which starts the server
21+
* core/: The core directory contains the most important files of the project like database, mailer, router and main controller
22+
* core/entryController.js: Is the main controller for all the requests
23+
* core/restapi.js: All routes can be found here, they will also be listed further down
24+
* mails/: The mails directory holds the mail templates
25+
* public/: The public directory is not used for now
26+
27+
28+
**DATABASE**
29+
30+
We use MySQL for the COC API as our relational database.
31+
Currently all of the database related code can be found in the `core/db.js` file.
32+
This includes the credentials for the database (host, user, password and db name) and can be changed in this file.
33+
34+
TODO: Add description of tables
35+
36+
**MAILER**
37+
38+
The code related to the mail system can be found in the file `core/mailer.js`.
39+
For the mailer to work the smtp credentials need to be changed in this file as well.
40+
Then the mailer will work and use the mail templates from `mails/entry/`
41+
42+
43+
## Installation
44+
45+
**PREREQUESITES**
46+
47+
Before starting the installation you need to make sure you have the following tools installed:
48+
* Git: You need to have Git installed. You can check this in the console with `git --help`. For installation instructions visit https://git-scm.com/
49+
* Node.js: You need to have Node.js installed. You can check this in the console with `node -v`. For installation instructions visit https://nodejs.org/en/
50+
* Npm: You need to have npm installed. You can check this in the console with `npm -v`. For installation instructions head to https://www.npmjs.com/get-npm
51+
52+
**INSTALLATION**
53+
54+
1. First you need to clone the git repository of the Clock of Change API. Head to a directory where you want the git repository to reside
55+
and open the directory in the console. Then run `git clone https://github.com/Human-Connection/Clock-of-Change-API.git` to clone the repository to this directory.
56+
2. Go to the newly created Clock-of-Change-API directory (`cd Clock-of-Change-API` in the console) and run `npm install`.
57+
Now all the dependencies should install.
58+
3. Edit the file `core/db.js` and add your MySQL credentials (host, user, password, database name).
59+
4. Create the tables - TODO: Add create table script & insert start values
60+
5. Edit the file `core/mailer.js` and add your smtp credentials (host, user, password)
61+
62+
Now the Clock of Change API server is ready to tick.
63+
64+
## Usage
65+
66+
**START THE SERVER**
67+
68+
In the base Clock-of-Change-API directory run
69+
70+
`npm run start`
71+
72+
in the console to start the Clock of Change API server.
73+
This will start Nodemon and the Node.js server, which will start listening for and processing requests at [http://localhost:1337](http://localhost:1337).
74+
75+
**MAKE REQUESTS**
76+
77+
Pro Tip: Get [Postman](https://www.getpostman.com/) to make requests. This amazing tool makes working with APIs way easier.
78+
79+
When using the default port 1337 (which you do if you haven't changed it in server.js), you can send requests to the Clock of Change API to `http://127.0.0.1:1337`.
80+
81+
Refer to the list of routes below, to see all possible requests with description you can make.
82+
83+
**ROUTES**
84+
85+
List of routes / endpoints
86+
87+
| Method | URI | Description |
88+
|---|---|---|
89+
| GET | http://127.0.0.1/cube.php | - Temp Route until path can be changed<br/>- Returns the current number of confirmed entries<br/>- No authentication required<br/>- Returns a number/string (we change to json once we can adjust hardware clocks) |
90+
| GET | http://127.0.0.1/entries/verify/:k | - Verify an entry with a email validation link/hash :k (for example http://127.0.0.1/entries/verify/sadSdjsarj3jf3j3wfmwfj3w)<br/>- Returns Json {success : true || false, invalidKeyError if hash is invalid/used} |
91+
| POST | http://127.0.0.1/entries | - Requires auth (see AUTHENTICATION)<br/>- Create a new entry from body parameters<br/>- Body parameters: firstname, lastname, email, country, message, anon (int 0 or 1), image<br/>- Returns Json {success : true}<br/>- May return errors mimeError, sizeError, missingFields, fieldErrors, missingImageError |
92+
| GET | http://127.0.0.1/entries | - Requires auth<br/>- Get back all entries<br/>- Parameters: limit (default 10), offset (default 0) and active (default false)<br/>- If active is true, only confirmed and active accounts will be returned<br/>- Returns Json {success : true, results : out, totalCount : results.length, page : offset} or<br/> - Return {success : false, message : "error"}|
593

694
**AUTHENTICATION**
795

8-
to authenticate simply send API-Key in each requests headers
9-
10-
**USAGE:**
11-
12-
if you have nodemon installed from dev dependencies use "npm start"
13-
to run the Server, the default port is 1337.
14-
15-
to ensure emails are working properly make sure to set your smtp credentials in
16-
/core/mailer.js this will use templates from /mails directory.
17-
18-
*DATABASE*
19-
20-
we use mysql for the coc api right now we have 2 tables entries and apikeys
21-
22-
once the server is running you can use the following routes:
23-
24-
GET http://127.0.0.1/cube.php
25-
- return the current count of entries with email_confirmed === 1 && status === 1
26-
- no auth required
27-
- returns the number (we change to json once we can adjust hardware clocks)
28-
GET http://127.0.0.1/entries/verify/:k
29-
- verify an entry with a valid link parameter :k for example http://127.0.0.1/entries/verify/sadSdjsarj3jf3j3wfmwfj3w
30-
- no auth required
31-
- returns {success : true || false, invalidKeyError if key is invalid/used}
32-
POST http://127.0.0.1/entries
33-
- call with body data firstname, lastname, email, country, message, anon (int 0 or 1), image to create a new entry
34-
- requires auth (see **AUTHENTICATION**)
35-
- returns {success : true}
36-
- may return errors mimeError, sizeError, missingFields, fieldErrors, missingImageError
37-
38-
GET http://127.0.0.1/entries
39-
- to get back all entries allowed parameters are limit (10), offset (0) and active (false)
40-
where active will return items which have email_confirmed === 1 AND status === 1
41-
- requires auth
42-
- returns {success : true, results : out, totalCount : results.length, page : offset}
43-
- return {success : false, message : "error"}
96+
To authenticate simply send parameter "API-Key" and the API key as the value with each request in the header
97+
98+
<br/>
99+
<br/>
100+
101+
```
102+
_____
103+
_.'_____`._
104+
.'.-' 12 `-.`.
105+
/,' 11 1 `.\
106+
// 10 2 \\
107+
;; ::
108+
|| 9 ---O----- 3 ||
109+
:: ;;
110+
\ 8 4 //
111+
\`. 7 5 ,'/
112+
'.`-. __6__ .-'.'
113+
((-._____.-))
114+
_)) ((_
115+
'--' COC '--'
116+
```

‎docker-compose.yml‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
version: '3'
2+
3+
services:
4+
db:
5+
image: mysql:5
6+
environment:
7+
MYSQL_ROOT_PASSWORD: 123456
8+
MYSQL_DATABASE: db1
9+
10+
coc-api:
11+
image: clock-of-change-api
12+
build:
13+
context: .
14+
volumes:
15+
- ".:/home/node/coc-api"
16+
- "/home/node/coc-api/node_modules"
17+
ports:
18+
- 1337:1337
19+
environment:
20+
- DB_HOST=db:3306
21+
- DB_NAME=${MYSQL_DATABASE}
22+
- DB_USER=root
23+
- DB_PASSWORD=${MYSQL_ROOT_PASSWORD}
24+
depends_on:
25+
- db
26+
command: "npm run start"

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
"description": "clock of change api",
55
"main": "server.js",
66
"scripts": {
7-
"start": "nodemon server"
7+
"start": "nodemon -L server.js"
88
},
99
"author": "Sebastian Koch",
1010
"license": "GPL-2.0",

0 commit comments

Comments
 (0)