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
<palign="center">ReactJS + Flask + Docker<br/>boilerplate using a token-based LDAP authentication</p>
9
+
<palign="center">ReactJS + Flask + Docker (+ K8S)<br/>boilerplate using a token-based LDAP authentication</p>
10
10
11
11
> :smiley: Suggestions and feedbacks are [highly appreciated](https://github.com/flavienbwk/reactjs-flask-ldap-boilerplate/issues/new)
12
12
@@ -15,17 +15,18 @@
15
15
- Docker architecture
16
16
- LDAP authentication
17
17
- Token-based API authentication
18
-
- Automatic [token renewal](./api/app/service/auth_service.py#L44) with [a Flask middleware](./api/app/service/auth_service.py#L31)
18
+
- Automatic [token renewal](./api/app/service/auth_service.py#L45) with [a Flask middleware](./api/app/service/auth_service.py#L32)
19
19
- Swagger documentation
20
20
- Flask-Migrate
21
21
- Flask-SQLAlchemy (PostgreSQL was chosen)
22
-
-[Logging and logs rotation](./api/app/utils/Logger.py#L12)
23
-
-[Choose](./app/app/src/App.js#L64) between sidebar and navbar (or use both !)
22
+
-[Logging and logs rotation](./api/app/utils/Logger.py#L11)
23
+
-[Choose](./app/app/src/App.js#L65) between sidebar and navbar (or use both !)
24
24
- Responsive design
25
+
-[Production](./prod.docker-compose.yml) and [development](./docker-compose.yml) builds
25
26
26
27
## API documentation
27
28
28
-
I chose to use Swagger to document the API. Just run the API following the steps below and browse to [`http://localhost:5000`](http://localhost:5000)
29
+
We've chosen Swagger to document the API. Run the API following the steps below and go to [`http://localhost:5000`](http://localhost:5000).
29
30
30
31
Here you can take a look at the database architecture scheme :
31
32
@@ -35,76 +36,144 @@ Here you can take a look at the database architecture scheme :
35
36
36
37
> Reminder : there is no `password` field because we use LDAP for authentication.
37
38
38
-
## Setting up the API
39
+
## Why using LDAP authentication ?
39
40
40
-
The API is made to run with an LDAP server for managing users. Whether use the provided Docker LDAP server or remove the conf. in [`docker-compose.yml`](./docker-compose.yml) and use your own LDAP server.
41
+
LDAP services are used in a lot of companies and institutions around the world to manage their user accounts and rights in a central place.
41
42
42
-
This section will explain to you how to run this project and set-up the LDAP server with one user.
43
+
With this boilerplate, you will be able to develop corporate-ready services AND avoid yourself the troubles of developing registration / password forgotten / change password / profile update code.
43
44
44
-
### Starting services
45
+
##Getting started (development)
45
46
46
-
First, please change the database/LDAP passwords and keys in `docker-compose.yml`
47
+
This section will explain how to properly run this project and set-up the LDAP server with one user.
47
48
48
-
Then, run :
49
+
1. Copy the `.env.example` file to `.env`
49
50
50
-
```bash
51
-
docker-compose up ldap phpldapadmin database adminer -d
52
-
```
51
+
```bash
52
+
cp .env.example .env
53
+
```
53
54
54
-
> **adminer** (PostgreSQL management) will be available through `http://localhost:8082`
55
-
> **phpLDAPAdmin** (LDAP management) will be available through `https://localhost:8081`
55
+
> This is a good practice so your `.env` can't be committed along with your modifications (is in `.gitignore`)
56
56
57
-
### Creating the first user in the LDAP
57
+
2. Start the authentication services
58
58
59
-
Access phpLDAPAdmin with : `https://localhost:8081`
59
+
```bash
60
+
docker-compose up ldap phpldapadmin database adminer -d
61
+
```
60
62
61
-
If you are not familiar with LDAP, [read my LDAP user creation guide](./CREATE_LDAP_USER.md) to add your first user
63
+
- **phpLDAPAdmin** (LDAP management) will be available at `https://localhost:8081`
64
+
- **adminer** (PostgreSQL management) will be available at `http://localhost:8082`
62
65
63
-
### Run the API
66
+
**Create** your first user by accessing phpLDAPAdmin at `https://localhost:8081` and [following the LDAP user creation guide](./CREATE_LDAP_USER.md).
64
67
65
-
The database will be automatically set-up thanks to Flask Migrate and any future modification brought to [models](./api/app/model) will be automatically applied to the database when the API is **restarted**.
68
+
3. NGINX reverse-proxy
66
69
67
-
```bash
68
-
docker-compose up api
69
-
```
70
+
This boilerplate includes NGINX as a reverse proxy so we can have a unique endpoint for our app and API. Else, we would have to open two endpoints : one for the app, the other for the API.
70
71
71
-
Access the API and its documentation browsing [`http://localhost:5000`](http://localhost:5000)
72
+
```bash
73
+
docker-compose up --build -d nginx
74
+
```
72
75
73
-
## Setting up the web application
76
+
> NGINX will auto restart until you have started the app and API below.
74
77
75
-
:clock9: This step may take quite a lot of time due to npm's initial modules download
78
+
4. Run the API
76
79
77
-
Just run :
80
+
The database will be automatically set-up thanks to Flask Migrate and any future modification brought to [models](./api/app/model) will be automatically applied when the API is **restarted**.
78
81
79
-
```bash
80
-
# Build is quick, **first** launch is long (expect at least 5 min.)
81
-
docker-compose up app
82
-
```
82
+
You might wait some time before the database get updated after starting the API :
83
83
84
-
You can now enjoy the app on [`http://localhost:8080`](http://localhost:8080)
84
+
```bash
85
+
docker-compose up --build -d api
86
+
```
85
87
86
-
> :information_source: If you want to add a dependency, just stop & re-launch a `docker-compose up app`. You won't have to wait as for first launch.
88
+
> For development, go to [`http://localhost:5000`](http://localhost:5000) to access the API documentation
87
89
88
-
## Why using LDAP authentication ?
90
+
5. Run the web app
89
91
90
-
LDAP services are used in a lot of companies and institutions around the world to manage their user accounts and rights in a central place.
92
+
```bash
93
+
# Expect several minutes for first launch (npm install)
94
+
docker-compose up --build -d app
95
+
```
91
96
92
-
With this boilerplate, you will be able to develop corporate-ready services AND avoid yourself the troubles of developing registration / password forgotten / change password / profile update code.
97
+
> :information_source: If you want to add a NPM package, just stop & re-launch `docker-compose up app`.
98
+
99
+
Enjoy the app on [`http://localhost:8080`](http://localhost:8080)
100
+
101
+
## Deploy to production
102
+
103
+
1. Prepare environment configuration
104
+
105
+
Copy `.env.example` to `.env` and **edit** the passwords, keys and credentials
106
+
107
+
Use the provided Docker LDAP server or edit the config to use your own.
108
+
109
+
```bash
110
+
cp .env.example .env
111
+
```
112
+
113
+
2. Build the application for production
114
+
115
+
```bash
116
+
docker-compose -f prod.docker-compose.yml build
117
+
```
118
+
119
+
3. Start the authentication services
120
+
121
+
```bash
122
+
docker-compose up ldap phpldapadmin database adminer -d
123
+
```
124
+
125
+
**Create** your first user by accessing phpLDAPAdmin at `https://localhost:8081` and [following the LDAP user creation guide](./CREATE_LDAP_USER.md).
126
+
127
+
:information_source: We recommend you to hide this service behind a firewall
128
+
129
+
4. Run the application
130
+
131
+
```bash
132
+
docker-compose -f prod.docker-compose.yml up nginx api app -d
133
+
```
134
+
135
+
Access the UI at `https://localhost:8080`
136
+
137
+
### Deploy to K8S
138
+
139
+
I pretend you have here your K8S instance configured to be accessed by your `kubectl` CLI.
140
+
141
+
I've used [Scaleway Kapsule](https://www.scaleway.com/en/kubernetes-kapsule) to perform my tests. This is an easy way to have a Kubernetes cluster quickly ready.
142
+
143
+
1. Building production images (optional)
144
+
145
+
Images are tagged `flavienb/reactjs-flask-ldap-boilerplate-{api,web,nginx}:latest` by default. Edit it in`prod.docker-compose.yml` before building.
146
+
147
+
:information_source: You might be interested in pushing your images in a private registry (e.g: [Scaleway's Container Registry service](https://www.scaleway.com/en/container-registry/)).
148
+
149
+
```bash
150
+
docker-compose -f prod.docker-compose.yml build
151
+
```
152
+
153
+
Finally, `docker push` the 3 images and edit K8S' configurations :
154
+
155
+
- [k8s/app.yaml, line 31](k8s/app.yaml#L31)
156
+
- [k8s/api.yaml, line 21](k8s/api.yaml#L21)
157
+
- [k8s/nginx.yaml, line 21](k8s/nginx.yaml#L21)
158
+
159
+
2. Add a new `reactjs-flask-ldap-boilerplate` namespace
93
160
94
-
## Left TODOs
161
+
```bash
162
+
kubectl create namespace my-app
163
+
```
95
164
96
-
API :
165
+
3. Configure your Ingress app endpoint
97
166
98
-
_Completed_
167
+
- **Edit** the env variables in [k8s/env-configmap.yaml](./k8s/env-configmap.yaml)
168
+
- **Edit** the app and phpldapadmin endpoints in [k8s/ingress.yaml, line 10 and 35](./k8s/ingress.yaml#L10)
169
+
- **Check** the PersistentVolumeClaim if you're not using Scaleway in all `*-pvc.yaml` files
99
170
100
-
App :
171
+
Deploy with :
101
172
102
-
_Completed_
173
+
```bash
174
+
kubectl apply -f ./k8s
175
+
```
103
176
104
-
Architecture :
177
+
4. Configure the first user
105
178
106
-
-[P3] Add "Deploy to prod" guide in README
107
-
-[P3] Create a `prod.docker-compose.yml` file that :
108
-
- Uses NGINX with SSL
109
-
- Builds & serves the front-end
110
-
- Disables Swagger UI
179
+
**Create** your first user by accessing phpLDAPAdmin at [endpoint defined](./k8s/ingress.yaml#L35) and [following the LDAP user creation guide](./CREATE_LDAP_USER.md).
0 commit comments