Elucidate Winter 2022
Table of Contents
Technologies
Frontend
Backend
- Web server
- Database
- Linting
- Formatting
Other
- Documentation
Getting started
Setting environment variables
- Create a copy of the
.env.example
file. (Do not delete or replace the original.env.example
). - Rename the copy to
.env
.
Installing Docker
Windows
- Once docker is installed, try running it. If docker-engine starts successfully, you can proceed.
- If your docker requires you to install WSL, you can easily do so by the following steps:
- Open PowerShell with administrator privileges.
- Type
wsl --install
. - Restart your computer and try running
wsl
in cmd. If you get no error, then you are all set.
- If you get an error about needing to update the kernel, you can do so by installing this package.
- Then run
wsl --set-default-version 2
.
- Then run
- If you are asked to enable Windows Virtualisation Platform, or Hyper-V then:
- Run
bcdedit /set hypervisorlaunchtype auto
in an admin privilege PowerShell and restart your computer.
- Run
- Once docker-engine is running successfully, you can close the docker window, as it should continue running in the background.
Linux
- If you are running Linux, Docker compose will not be automatically installed. You will need to install it manually by following this guide.
Potential Errors While Running The Docker Container
-
Windows : If the client and/or server containers fail to run due to
runtime.sh
not being found, then you need to change the line endings of theruntime.sh
file (located indocker/client/
anddocker/server
) from CRLF to LF.- You can do this in VS Code by opening the
runtime.sh
file, and in the bottom-right corner, click on CRLF. A dialogue box pops up, click on LF and save the file.
- You can do this in VS Code by opening the
-
Mac :
- Linux :
Development environment setup
- Install the
Docker
and theRemote - Containers
extensions.
- Navigate to the remote explorer tab.
- Click the
Open Folder in Container
button and open theclient
folder.
- The first time this is launched, it may take up to 5 minutes to install and configure everything.
- After you are shown the workspace, there should be a pop-up at the bottom right asking you to install recommended extensions. Click install.
- Afterwards, close out of the remote container.
- Navigate to the remote explorer extension tab again. If you see the below, then the frontend workspace has been successfully configured.
-
Press the plus symbol.
-
Click open folder in container.
- Select the
server
folder.
- Again, wait until the installation process completes, install the recommended extensions, and exit the container.
- If you now navigate to the remote explorer tab, you should see 3 containers; one for frontend, backend, and database.
- The installation process is now complete.
Development
-
To start developing, navigate to the remote extensions tab. Hover over the frontend or backend container and click the folder icon.
-
Note, for the backend, you may need to start the database container first. To do so, right-click on the database container and click
Start Container
.
Writing documentations
We will be using MkDocs to generate the documentations for this project. MkDocs is a documentation generator that is based on Markdown.
Using MkDocs
- Using the remote explorer extension tab, open the folder inside the
documentation
directory. This is the same process as setting up the workspace. - Run
mkdocs serve
to launch a development server.
Development workflow
- Decide as a team the issue/s you want to work on.
- Assign yourselves to the relevant issue on GitHub.
- A branch corresponding to the issue should be created (unless it is a point 5 issue).
- Checkout the branch corresponding to the issue. It should be in the format of
i<issue number>-<issue_name>
. - Work on your changes.
- Make commits and push them to the issue branch.
- Open a pull request on GitHub.
- Await for code reviews.
- Your feature is merged!
- Delete your local branch with
git branch -d <branch_name>
.