Getting started

Getting started with the td-uit dev environment

This is an attempt at an exhaustive tutorial of how to setup the td frontend and backend dev environments, and how to start working on your first issue! We'll try to cover as much as possible to get you started while avoiding overwhelming you. As the experience of our contributors can vary vastly we might cover topics you are already familiar with; feel free to jump ahead!

Note

If something is unclear, missing or incorrect, please do not hesitate to either create an issue in our issue tracker, or by submitting a pull request! This wiki is also part of this open source project, feel free to contribute 🚀

Installing dependencies 📦

Before we get going, there are a couple of dependencies we'll need to run the development environment. We'll have a quick look at them here.

Docker 🐳

We use Docker to run our frontend react app, backend server and database all in their own container. Therefore, we'll need to install docker engine. Navigate to your OS and follow the steps to install it.

After installing docker engine, you will either have to start the Docker Desktop application (Windows/macOS), or start the docker daemon from the commandline (Linux). This command might vary among distros, take a look in the linked page corresponding to yours!

Now, we can check that our docker daemon is running correctly by building a hello world container:

sudo docker run hello-world

That should print out hello world in the terminal!

Node/Yarn 🧶

When developing the frontend, it is a good idea to install the node packages on your local machine. This way, your code editor will know about the packages we use, and you'll avoid getting a ton of errors and get that handy auto completion. We currently use node as our javascript runtime and Yarn as our package manager.

Note that this step is not required for you to run the frontend; the Docker container already has yarn and all other necessary dependencies installed and will work as long as the Docker daemon is there to run it!

1. Install Node.js First, we'll have to install Node.js on our system. Even though the container is running an older version, we'll grab the LTS version from the installation page and install according to the instructions for your system.

2. Install Yarn Now, with Node.js, we've also got a CLI tool installed called npm. We'll use this tool from the commandline to install Yarn:

npm install --global yarn

Now, we'll check that yarn was indeed successfully installed:

yarn --version

Python and pipenv 🐍

For the backend, we'll also want Python and pipenv so that we can install the packages we use on the server. Similarly to installing node/yarn the frontend, this will make development life much easier.

If you don't already have Python 3.x (meaning 3.0 or later) installed, grab it from the download page or install/upgrade it using your Linux package manager. This install should also come with PIP3, which we will use to install pipenv. Test out your install from the commandline:

python --version

Make sure this version is 3.0 or later!

Now, we'll install pipenv:

pip3 install pipenv

You can check that it installed correctly as well

pipenv --version

Setting up the environment

Alright, now that we've got all our dependencies installed and ready to go, we can finally download the code and set up our development environment on our machine!

Clone the projects ⬇️

To download the code, we'll just have to create a directory for each of the frontend and api projects and clone them via git. Follow the guide in the frontend README and correspondingly in the backend/api README.

Be sure to try building and running the projects as described!

Download packages 📦

Remember how we installed yarn and pip3 earlier in the tutorial? Now, we'll have to use these tools to download the packages to our machine so that the language server and linter in the code editor can understand our use of external packages and give us auto complete.

1. Frontend For the frontend, open a terminal and make sure that you are in the root folder of the frontend project. Using

ls

you should be able to see amongst others the packages.json and yarn.lock file. Now, we'll install all the dependencies using a simple command:

yarn install

This should install all the required packages and their correct versions on your machine. Open the src/ directory in your favorite code editor and see whether it worked!

2. Backend For the backend, we'll need to cd into the root directory of tdctl_api. Like we did before, use ls to check whether the Pipfile is there. Now, we'll use pipenv to install the packages into a virtual environment for us.

pipenv install

This command will install the packages we have specified in the Pipfile. It might take a little while, and may also update the Pipfile.lock file in the process. Once it's done, it will tell us to enter our newly created environment with the following command:

pipenv shell

This will place us in the virtual environment where all our python packages exist. If you're on macOS or linux, run your favorite editor through the commandline inside this virtual environment. For instance, vscode can be run like this:

code .

If you're on windows, you might have to specify the correct interpreter from the virtual environment we created so that the interpreter knows about our packages. In vscode we can do the following:

1. ctrl+shift+P to open the command pallette
2. Search for "Python: Select Interpreter"
3. Select the interpreter corresponding to our virtual environment. It should say "PipEnv" on the right hand side and have "tdctl-api" in its name

Running the web app 🏃‍♂️

Now that we've set up our dev environment, it's time to run our web app and check it out! All we have to do is run both the frontend and api in docker containers. As we've seen in brief earlier, we've created a handy utility script for each to easily run all the containers we need. Run the containers using

./dev_utils.sh compose up

This will build, configure and run the containers needed for the respective project. You can also pass in -d as a flag to this command to run the container in the background, in which case you'll need to stop it with

./dev_utils.sh compose down

With both containers running, go to your browser and go to localhost:3000 to see the app. It should look like the td-uit website, but lacking any events or other data. We'll fix that now!

Seeding the database 🌱

In order to see how the website looks with users, events, jobs and so on, we'll have to seed the database with some sample data that we've created in advance. This is easy to do with the utils script provided:

./dev_utils.sh seed

Boom.

Now look at your app again in the browser; there should be some sample events there now.

Logging in

A lot of the functionality on the website is only available to admins, and therefore you'll need to sign in with an admin account we created during the seeding process. The credentials are as follows:

username: [email protected] password: Admin!234

If you want to test out functionality available to normal users, but not admins, simply create a new user through the sign-up process.

Contributing

With the dev app all set up and ready to go, you're ready to contribute! 🚀 Way to go, friendo, I know you had it in you! Now, we'll go ahead and choose and issue to implement and create a branch for it. The issues are all nicely organized in our project. Pick one that seems doable for you, and more importantly one you want to do. We've labelled the issues we feel are good to start of with Good first task to make it easier for you to choose. Now, assign yourself to that issue to tell everyone that you're working on it and go back into your terminal (or wherever you prefer to deal with git).

Now we'll create a fresh branch to commit our changes to. Make sure you're on the master branch by checking it out

git checkout master

and be sure to pull in case some new changes have been made upstream (git pull). Now, we'll create our own branch from master:

git checkout -b feature/example-feature

The name of your branch is not really that important, but if you want to keep it clean, check out the CONTRIBUTING.md file to see how we prefer to name our branches. Now you're ready to start writing some code!

Note

When trying to push your branch upstream, you might discover that you don't have write permission. Currently, only members of our organization on github have write permissions to our repositories. Reach out to the "nettsideansvarlig" or anyone else with admin privileges and we'll add you!