Skip to content

Latest commit

 

History

History
306 lines (211 loc) · 10.9 KB

README.md

File metadata and controls

306 lines (211 loc) · 10.9 KB
Raw

iscsc.fr

This is the iScsc website source code. This website is still under development

MERN

The tech stack I chose for this web application is MERN with:

  • MongoDB for the database
  • Express for the API
  • React for the frontend
  • Node.js for the backend

For more information, check this article. You can also watch this video if you want to get more familiar with the stack. If you're a true beginner, you can follow this Open Classroom course.

Table of contents

  1. Functionalities
  2. Deployment
    2.1 Setup the local MongoDB folder
    2.2 Development mode
    2.3 Production mode
  3. Repository structure
  4. Bugs and recommendations
  5. Upcoming work

1. Functionalities (toc)

The main functionalities of the website at the moment are creating, reading, and deleting posts on the blog section of the website. Posts are rendered in Markdown, with the Github Flavored Markdown, GFM. The authentication is now available. A user can sign up and log in with an email and a password. Some actions in the blog, like creating and deleting articles, need authentication. JWT and cookies allow the user to stay logged in.

Create

You should be able to create your post in the /create-article route. Creating a post requires authentication.

Two writing options are available:

  • Writing the post directly inside the form inputs
  • Submitting a markdown file

For the first option, no editor is available at the moment on the website, so writing a post directly from the Textarea field might be harsh. That is why the second way is recommended. A template is available for the markdown file submission.

When creating a post, a preview is available on the right side of your browser. The author assigned to the article will be the name of the authenticated user.

Read

Any article submitted by other users can be read through the /blog route.

Delete

You should be able to delete any article you created from the database.

Note: if you try to delete an article you did not write, it won't work but you won't receive any error message.

2. Deployment (toc)

You need to setup 3 things to run the website:

  • .env.* file
  • MongoDB host folder
  • start frontend, backend and database

For deployment, development and production modes are available

Notes for the iScsc members:

Send me a message, and I'll send you back an encrypted version of the official .env.production and .env.development files.

Here is a quick guide after cloning the repository:

2.1 Setup the local MongoDB folder (toc)

To make the database persistent through containers starting and stopping the database folder is shared with the host using a docker volume, you can see it in the docker compose files.

⚠️⚠️ IMPORTANT: the following script will give rwx permissions on the DB folder to the UID 1001 due to bitnami/mongodb image constraint (the Note under "Persisting your database"), if, on your systemn, it already exists and shouldn't have these access please consider modifying the image!

However because the bitnami/mongodb container is a non-root container we've got to setup the right permission on that folder.
To set it up just run

./scripts/setup-db-folder.sh

2.2 Development mode (toc)

You have two choices to run the development mode:

.env.development file

Before deploying the application, you need to set the environment variables.
From the root directory of the repository, do the following:

cp .env.example .env.development

After copying the example config of .env, you must fill in the missing information in this file. Check the example for more information.

Docker

Once your .env.development is ready, run

docker-compose --env-file .env.development --file docker-compose-dev.yml up -d --build

Make sure the docker daemon is running with systemctl status docker, or start it with systemctl start docker

The website is now up on $CLIENT_URL (specified in the .env.development file)

To see the running application, and check the logs use

docker ps
docker logs <CONTAINER_ID>

Finally, you can stop it with

docker-compose --env-file .env.development --file docker-compose-dev.yml down

Manually on host

Backend

From the root directory of the repository, do the following:

cd backend
npm install
npm run dev

You will need nodemon to run the backend. Use npm install -g nodemon to install it. Make sure you're supporting at least 2.0.20 with nodemon --version. Nodemon has been tested working fine with node 19.

Frontend

From the root directory of the repository, do the following:

cd frontend
npm install
npm run start

Make sure you're using at least version 8.19.2 by checking npm --version, and update if needed with npm update.

Database

Start a MongoDB either in a container and expose a port or directly on your host with the right port configured. Then setup properly the .env, it should work but this is untested.

2.3 Production mode (toc)

The production mode allows to deploy the application on the server. To use it, you will need:

  • docker
  • docker-compose

.env.production file

Before deploying the application, you need to set the environment variables as for development mode.

cp .env.example .env.production

SSL certification

To set up HTTPS, you will need valid SSL certificates. If you deploy the app for the first time, follow these instructions:

  • Comment or delete the whole server section about 443 in the nginx/nginx.conf.template file.
- server {
- listen 443 default_server ssl http2;
- ...
- }

This step is required because the certificates don't exist yet, so they cannot be loaded in the nginx configuration.

  • (Re)Start the nginx container:
sudo docker-compose --env-file .env.production up -d --build
  • Create the certificates with the certbot container:
sudo docker-compose --env-file .env.production run --rm certbot certonly --webroot --webroot-path /var/www/certbot/ -d yourdomainname.com
  • Restore the original nginx/nginx.conf.template (with git restore nginx/nginx.conf.template for example)
  • Stop the nginx container:
sudo docker-compose --env-file .env.production down

The certificates should have been generated in certbot/conf/live/yourdomainname.com/

If you just want to renew existing certificates, use:

sudo docker-compose --env-file .env.production run --rm certbot renew

Docker

Once everything is ready, run

sudo docker-compose --env-file .env.production up -d --build

Make sure the docker daemon is running with systemctl status docker, or start it with systemctl start docker

Your application can now be started on $CLIENT_URL (specified in the .env.production file)

To see the running application, and check the logs, use

sudo docker ps
sudo docker logs <CONTAINER_ID>

Finally, you can stop the production mode with

sudo docker-compose --env-file .env.production down

3. Repository structure (toc)

Here is a list of the main folders/files of the repository.

iscsc.fr
│
├── .env.development    *stores database credentials and required information for development mode deployment. Must be created*
├── .env.production     *Same thing for production mode. Must be created*
├── .env.example        *template for .env files*
│
├── backend             *contains the server-side code and API*
│   ├── Dockerfile          *Dockerfile to build the backend container*
│   ├── controllers/        *useful js functions for each model*
│   ├── middleware/         *js functions that run between the frontend and backend*
│   ├── models/             *contains the database models*
│   ├── routes/             *routes and functions to executes for each model*
│   └── app.js              *main application for the backend*
│
├── frontend
│   ├── public              *automatically generated files and images that are publically available for the user*
│   ├── Dockerfile          *Dockerfile to build the frontend container*
│   └── src                 *source code of the website*
│       ├── components/         *source code of main components of the website*
│       ├── context/            *defines the context function to keep track of data with useReducer*
│       ├── hooks/              *defines the hooks that trigger the context functions*
│       ├── pages/              *source code of the pages of the website*
│       ├── App.js              *defines the routes of the application*
│       ├── index.js            *main js application of the website*
│       └── index.css           *css styling file of the website*
├── scripts
│   └── gpg-share.sh        *share a secret file to others with pgp keys*
│
├── nginx               *reverse proxy server for the production mode*
│   ├── Dockerfile          *Dockerfile to build the nginx container*
│   ├── run_nginx.sh        *script to generate the nginx conf from the template*
│   └── nginx.conf.template *template for the nginx conf, needs to be filled with env variables*
│
├── bump.sh             *script used to bump version of frontend, backend, and whole website*
├── docker-compose.yml  *docker compose config file to deploy the website in production mode*
├── package.json        *contains the current version and information about the website*
└── README.md           *this file*

4. Bugs and recommendations (toc)

Because this website is still in development, do not hesitate to open an issue if you experience any trouble using it. Also, feel free to share your recommendations regarding the color scheme, routes, design, UX, etc...

5. Upcoming work (toc)

Here is a non-exhaustive list of incoming functionalities for the website:

  • User profile, with article management
  • Likes and comments
  • Main page
  • Calendar
  • News and events
  • Pictures, avatars for users
  • Search bar
  • Gallery with previous works, events
  • Videos integration
  • ...