Setting up your project
At this point, you have all of the tools necessary to work on our project installed -- Git, Atom, Python, Node/npm, and PyCharm -- so let's put it all together and get the project running.
If you have not yet completed the Technical Onboarding guide, you're in the wrong place. Head over to the Intro and get started there. You'll end up back here eventually.
Create your project
Go to the Github-hosted boilerplate repository.
Click the "Use this template" button on the top right.
On the screen with the heading "Create a new repository from boilerplate", change the owner to `dhmit` from the dropdown on the left, and add a project name. If you don't see `dhmit` in the dropdown, please ask DH staff about it, it's likely because you haven't been added to the team yet. The project name should be short but descriptive. This is just the name to find the project code by, so don't worry about it not being perfect.
Click "Create repository from template" button.
Cloning the Repository
Open GitHub Desktop. If this is your first time using the application and you've
already been added to the
dhmit organization, dhmit projects should appear in the repositories pane, under the "Filter
your repositories"
search box. Click on dhmit/your-new-project
, and
click Clone
dhmit/your-new-project
.
If this option doesn't appear, click Clone a repository from the
Internet...
or go to File
-> Clone repository
. In the URL tab, enter
dhmit/your-new-project
.
Leave the Local path
field as is, but take note of it, as you'll need it
later. Click Clone
to download the repo.
Once the repo is cloned, you should see a screen that looks like this. Try clicking on
Windows Show in
Explorer
or on macOS Show in Finder
to see where the project has ended
up on your computer,
or click View on GitHub
to go to our project page on GitHub.
Setting up our project in PyCharm
Open the project
Open PyCharm. In the menu bar, select File->Open, and open the folder where you cloned
the repo in the step
above. By default on Windows this is
C:\\Users\\YOUR_USER_NAME\\Documents\\GitHub\\your-new-project
and on macOS
/Users/YOUR_USER_NAME/Documents/GitHub/your-new-project
.
If you get this dialog box, always select "This Window" (the default) or "New Window" if you want to have multiple projects open at once. (Ryaan doesn't recommend the latter: PyCharm is very resource-intensive, so unless you absolutely need to have two projects open at once, click "This Window".)
Once it's loaded, you should see the
your-new-project
folder appear in the
Project
pane on the left.
Setup Python environment and packages
Open the settings window (macOS PyCharm -> Preferences
; Windows, File
->
Settings
), and go to "Project: your-new-project" ->
Python Interpreter. Click on the wheel in the top right and select "Add".
Select "New Environment". Make sure that the base interpreter is the path that you noted when installing Python. Leave the location for the interpreter as the default provided by PyCharm.
Apply your changes, wait for the virtual environment to be created, and exit the settings window.
Click Terminal
in the bottom status bar. You should see (venv)
at
the beginning of your prompt. If you do not, restart PyCharm and check again.
If you still don't see (venv)
appear, go back to the beginning of this section and make sure you correctly setup a new
environment.
Go back to the Project Interpreter window, and ensure that the Python Interpreter field is
populated with the
name Python 3.9 (your-new-project)
followed by a path. If this says anything else, find a staff member to get help fix it.
In the Project
panel, find and open the requirements.txt
file in
the top-level your-new-project
folder. Wait until PyCharm automatically detects that this file contains our Python package
requirements. Click
Install requirements
in the banner that pops up, and click Install
once the Choose
Packages to Install
window pops up. (If it asks you to install a plugin,
you can safely click Ignore extension
) You should see the installation process
begin in the bottom status bar. We can let this run while moving on to the next step,
but we'll come back to this to make sure it worked.
If this does not appear, go to the Terminal
and run the command
pip install -r requirements.txt
Setting up a Django run configuration
Our project uses Django, a Python web framework. If we let PyCharm know about Django, we get lots of nice debugging features.
Go back to the settings window. Under Languages & Frameworks
-> Django
.
Our project repository has some PyCharm settings saved within it, so it should look something like this. If it does, great, move on to Setting up a Backend Run Configuration.
Otherwise, if Enable Django Support
is not checked, then check it, and follow
the directions
below.
Set the Django project root
to be the backend
folder within our
project.
Set the Settings
file to be config/settings/dev.py
.
If the Django pane now looks something like this, you can click OK to apply and exit the settings.
Click the big Add Configuration
button in the top bar. In the Run/Debug
Configurations
window that appears, click the + in the top left corner, and select
Django
server
Name this configuration Run backend
and click OK
with all of the
defaults in place.
At this point in the process, you've installed all the third-party packages we need to
run our project and
made PyCharm aware of how to run our Django server. Let's check that everything worked.
Go back to the terminal inside Django, and execute pip freeze. This should
output a list that's
exactly the same as the contents of the requirements.txt
file you opened
earlier.
Type cd backend to enter the backend folder, and then run python manage.py migrate. This will setup a local development database on your machine.
Click the green triangular play button in the menu bar next to "Run backend" to run the Django development server. If everything is working, you should see some output like this in the run panel.
Click on the link where the site is being run locally http://127.0.0.1:8000, where you should see... well... a mostly empty page and a Hello world!
Navigate to http://localhost:8000/api/example/1, and you should see a Django REST framework debug page, which looks like this. If this is all working, we're nearly there! If not, try running the above steps again, and if all else fails, find a staff member or a returning lab member who can help you troubleshoot.
Setting up npm
Now that the Python/Django backend part of the site is up and running on your machine, the last step is to set up the JavaScript/React frontend.
In the project pane, find and open frontend/index.js
.
Do not click Run 'npm install'.
If you see a banner saying Switch language version to React JSX
, do
click that.
Go back to the terminal and issue the command npm ci. You might have to wait a little while now, as npm installs all of the Node modules we need to build the frontend.
Now, go back to what used to be the Add Configurations
button but now says
Run
backend
. Click Edit configurations
to go back to the Run/Debug
Configurations
window. Click the same + in the top left corner, and then select npm. Name this
configuration Run
frontend
.
The package.json
field should already be populated with a filepath to the
package.json
file at the root of the project, but not, click the dropdown
menu down arrow, and
select package.json
. This is the file that tells PyCharm and npm how our
frontend application is
configured.
Click OK and exit the settings. Once again, click the green triangle 'Run' button
next to Run frontend
which will start the frontend development server.
Once you see a success message in the run panel, go back to
http://localhost:8000, where you
should now see a page with the title "Boilerplate app".
Congratulations! You've got the project up and running on your machine.
Closing and restarting the project
Close PyCharm, terminate any processes when it asks, and then restart PyCharm. In order to
run the project, you
have to go to this dropdown menu, click Run backend
and then the triangular
'Run' button
next to it, and then click Run frontend
and do the same.
Once you see both Run backend
and Run frontend
tabs open in the
Run
panel, and both show success messages, you can go back to the site running locally on your
machine.
Please note that the frontend pane will show a url ending in :3000
. This is
another way to access the frontend directly without running the Django server.