This repository contains a template for creating a Django project ready to be deployed to Heroku via GitHub Actions or GitLab CI.
Untuk melihat berkas ini dalam bahasa Indonesia, klik di sini.
Create a directory for the project that you want to create (example:
project_name
), then open a Command Prompt (cmd) or Terminal in that
directory.
Create a Python virtual environment in it.
python -m venv venv
Note: please adjust the command with the
python
executable on your computer, because sometimes (example: on Ubuntu or macOS) Python 3 can only be executed usingpython3
, notpython
.
Activate the virtual environment that was just created.
On Windows:
venv\Scripts\activate
On Linux/macOS:
source venv/bin/activate
If successful, there should be (venv)
in your cmd/terminal prompt.
Install Django in the virtual environment.
python -m pip install Django
Create a new Django project with this template.
django-admin startproject --template="https://codeload.github.com/laymonage/django-template-heroku/zip/template" --extension="py,yml,md" --name="Procfile" project_name .
Note: rename
project_name
with the desired project name. Notice that there is a period (.
) at the end of the command. If there's an error when downloading the template from GitHub, please visit the link manually and point the--template
argument to the location of your.zip
file that you downloaded to your computer.
Sign in to Heroku Dashboard and create a new Heroku
application. The application name does not have to be the same as the
name of your Django project. Then, open up the Settings of the
application. In the Config Vars section, click the Reveal Config
Vars button. Add a variable named HEROKU_APP_NAME
with the name of your
Heroku app without .herokuapp.com
as its value. Then, add another
variable named SECRET_KEY
using a value generated by the
Djecrety site.
Create a new project/repository on GitLab/GitHub (choose one). Do not
select the options to initialize the repository with README.md
, license,
or .gitignore
. Just leave them blank.
If you use GitLab, go to the Settings menu in the left sidebar. In the
Variables section, add a variable named HEROKU_API_KEY
with the API
key of your Heroku account as its value. Then, add another variable named
HEROKU_APP_NAME
with your Heroku app name without .herokuapp.com
as
its value.
If you're using GitHub, do the same through the Settings > Secrets menu.
Note: Your Heroku account's API key can be viewed on Account settings.
If you use GitHub, move the tnd.yml
file to the .github/workflows
directory with the following commands.
On Windows:
mkdir ".github\workflows"
move tnd.yml ".github\workflows\"
On Linux/macOS:
mkdir -p .github/workflows
mv tnd.yml .github/workflows/
If you only use GitLab, you can delete the tnd.yml
file. If you only use
GitHub, you can delete the .gitlab-ci.yml
file.
Turn your project directory into a Git repository and create an initial commit.
git init
git add .
git commit -m "Initial commit"
Add a new remote named origin
that points to the repository you created
on GitLab/GitHub, then push to that repository.
git remote add origin https://gitlab.com/yourusername/project-name.git
git push -u origin master
Please check Pipelines on GitLab or Actions on GitHub. If the steps are followed correctly, then your Django project will be successfully deployed to Heroku.
Congratulations! Now, you just need to focus on developing your web project without having to worry about deployment problems. Before developing your web project, install the required packages with the following command.
python -m pip install -r requirements.txt
Continue by creating a local database and collecting static files into a single directory with the following commands.
python manage.py migrate
python manage.py collectstatic
After that, you can run your web server locally with the following command.
python manage.py runserver
From here, you just need to edit your Django project files as necessary.
Then, don't forget to use the git add
, git commit
, and git push
commands to upload your changes to GitLab/GitHub (which will then be
deployed to Heroku). Don't forget to make migration files if you change the
models.py
file.
python manage.py makemigrations
The generated migration files should be committed into the repository (unless you change the template configuration so that it's not necessary... but why?).
To run the unit tests, you can use the following command.
python manage.py test --exclude-tag=functional
After successfully creating a new Django project with this template, there are some highly recommended additional steps you can do in order to ease your web development in the future.
Add a new Django super user to your Heroku app.
The database used on your local computer is different to the one that's
used on Heroku. By default, you use the SQLite database stored in the
db.sqlite3
file, while Heroku uses the PostgreSQL database hosted in the
cloud.
To be able to access your existing Django administration site on Heroku,
open the Heroku Dashboard. Then, click on your app and click the More >
Run console option in the top right corner. Type bash
in the pop-up
dialog that appears. Then, enter the command python manage.py createsuperuser
and follow the instructions.
Psst, inside
bash
, you can browse your Django projects just like from the cmd/terminal! That means, you can also use other commands such aspython manage.py migrate
or even Linux shell commands.
Download chromedriver
(or any other webdriver you want) to your computer
in order to run functional tests locally. This will be very useful for one
of the stories.
On Windows:
Download ChromeDriver (chromedriver_win32.zip
) for the
Chrome version that you use. Then, extract the .zip
file and place the
chromedriver.exe
in this directory (same level as manage.py
).
On Linux:
Some Linux distributions have their own ChromeDriver packages, or some have
also included it in the chromium package (e.g. Arch Linux). If there is no
suitable package, you can download chromedriver_linux64.zip
from the link
above, then unzip
and put chromedriver
into one of the existing
directories in your $PATH
.
On macOS:
Install chromedriver
with Homebrew (brew cask install chromedriver
on the Terminal). Please install Homebrew first if you
haven't already. I don't have a macOS device, so please find a solution on
your own if there's any problem ;)
To run the functional tests only, use the following command:
python manage.py test --tag=functional
Note: if you want to use a different webdriver, please customize the
tests.py
file and install the webdriver accordingly. If you want to see the functional tests in action on your computer, turn off theheadless
option intests.py
. However, don't forget to turn it back on because the option is required by GitLab CI/GitHub Actions. Make sure you've run thecollectstatic
command before running the functional tests.
Note for Windows users: when you run functional tests, an error such as
ConnectionResetError: [WinError 10054] An existing connection was forcibly closed by the remote host
may appear. As long as the tests finish successfully, just ignore the error. This is a bug which has not been fixed for Django on Windows.
Set the code coverage configuration on GitLab.
Code coverage is a useful metric for measuring how much of your code is
covered by tests. GitLab has features for capturing code coverage from a
job log in the Pipelines. To set it up, go to CI/CD > General
pipelines. In the Test coverage parsing section, fill in the
following regular expressions: ^TOTAL.*s+(d+%)$
(what is this for?), and
save it.
Later, in the Coverage report section there will be a coverage badge of
your project. You can add this badge into the README.md
file just like
this one.
To run the tests with coverage on your local computer, use the following command.
coverage run --include="./*" --omit="venv/*,manage.py,project_name/*" manage.py test
Note: this command runs both unit tests and functional tests at once, so make sure you've run the
collectstatic
command before running the tests.
flake8
or pylint
. This is done to avoidblack
andisort
. It's a good idea to create a configuration to run theThe django-admin
tool provides the --template
option for the
startproject
command that accepts a path to a template of a Django project.
The path can be the location of a local file/directory or the URL for an
archive file. GitLab/GitHub provides the option to download repositories as
.zip
archives... you can figure out the rest :)
This template will then be rendered with variables that can be applied when
running the startproject
command. It works similarly to Django templates and
context variables that can be rendered into it.
Please use this template as a learning resource as much as possible. It is true that this template can make it easier for you to create Django projects that are ready to be deployed without having to deal with many configurations. However, it will be very beneficial for you if you understand how the configurations work in this template.
If you would like to contribute to this template, please create an issue or submit a pull request to the repository for this template at GitHub. This repository is also mirrored to GitLab for demonstration purposes.
This template is distributed under The Unlicense license. Projects generated with this template may be distributed under different licenses.