Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/laymonage/django-template-heroku
Simple Django project template ready for Heroku deployment for Web Design and Programming course at Fasilkom UI.
https://github.com/laymonage/django-template-heroku
django hacktoberfest heroku template
Last synced: 3 months ago
JSON representation
Simple Django project template ready for Heroku deployment for Web Design and Programming course at Fasilkom UI.
- Host: GitHub
- URL: https://github.com/laymonage/django-template-heroku
- Owner: laymonage
- License: unlicense
- Created: 2020-09-28T15:39:35.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2021-12-22T12:50:08.000Z (about 3 years ago)
- Last Synced: 2024-10-05T09:03:07.999Z (4 months ago)
- Topics: django, hacktoberfest, heroku, template
- Language: Python
- Homepage:
- Size: 79.1 KB
- Stars: 22
- Watchers: 2
- Forks: 6
- Open Issues: 1
-
Metadata Files:
- Readme: README.en.md
- License: LICENSE
Awesome Lists containing this project
README
# django-template-heroku
[![Test and Deploy][actions-badge]][commits-gh]
[![pipeline status][pipeline-badge]][commits-gl]
[![coverage report][coverage-badge]][commits-gl]
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][readme-id].*
## Table of contents
- [Table of contents](#table-of-contents)
- [Usage instructions](#usage-instructions)
- [Additional steps](#additional-steps)
- [Development tips](#development-tips)
- [What kind of magic is this?](#what-kind-of-magic-is-this)
- [Contributing](#contributing)
- [License](#license)
## Usage instructions
1. 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.
2. Create a Python virtual environment in it.
```shell
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 using `python3`, not `python`.
3. Activate the virtual environment that was just created.
On Windows:
```shell
venv\Scripts\activate
```
On Linux/macOS:
```shell
source venv/bin/activate
```
If successful, there should be `(venv)` in your cmd/terminal prompt.
4. Install Django in the virtual environment.
```shell
python -m pip install Django
```
5. Create a new Django project with this template.
```shell
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.
6. Sign in to [Heroku Dashboard][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][djecrety] site.
7. 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.
8. 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**][account-settings].
9. **If you use GitHub**, move the `tnd.yml` file to the `.github/workflows`
directory with the following commands.
On Windows:
```shell
mkdir ".github\workflows"
move tnd.yml ".github\workflows\"
```
On Linux/macOS:
```shell
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.
10. Turn your project directory into a Git repository and create an initial
commit.
```shell
git init
git add .
git commit -m "Initial commit"
```
11. Add a new remote named `origin` that points to the repository you created
on GitLab/GitHub, then push to that repository.
```shell
git remote add origin https://gitlab.com/yourusername/project-name.git
git push -u origin master
```
12. 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.
> Example: https://django-template-heroku.herokuapp.com
13. 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.
```shell
python -m pip install -r requirements.txt
```
14. Continue by creating a local database and collecting static files into a
single directory with the following commands.
```shell
python manage.py migrate
python manage.py collectstatic
```
15. After that, you can run your web server locally with the following command.
```shell
python manage.py runserver
```
16. 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.
```shell
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?).
17. To run the unit tests, you can use the following command.
```shell
python manage.py test --exclude-tag=functional
```
## Additional steps
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.
1. 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 as
> `python manage.py migrate` or even Linux shell commands.
2. 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] (`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][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:
```shell
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 the `headless`
> option in `tests.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
> the `collectstatic` 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][ticket-21227]
> which has not been fixed for Django on Windows.
3. 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.
```shell
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.
## Development tips
1. From now on, get used to reloading your browser with
Ctrl+Shift+R (you can also use
Shift+F5 on some browsers), not just
Ctrl+R or F5. Otherwise, when you develop
the web locally, you may often find that the static files that are loaded on
your browser do not change after you modify it. This happens because the
browser caches the static files for faster access. By pressing
Shift, the browser will [bypass the cached static
files][bypass-cache].
2. Get used to writing quality tests for your web projects, especially for the
logic parts such as those in the views layer. Writing tests will make it
easier for you to find bugs in your program early on. Besides, tests can
also prevent you from creating new bugs when you develop your web project.
3. 100% code coverage does not mean your project is bug-free. However, having
tests that assess your project as a whole will certainly be very useful.
Start writing tests every time you create a new functionality to maintain
your code coverage.
4. This template intentionally does not include linting configurations such as
using [`flake8`][flake8] or [`pylint`][pylint]. This is done to avoid
warnings from appearing on your GitHub Actions or GitLab CI if your code
does not comply with the rules applied by the linter. If you don't want to
be bothered with code style, I suggest using [`black`][black] and
[`isort`][isort]. It's a good idea to create a configuration to run the
linters on GitHub Actions or GitLab CI for your project.
## What kind of magic is this?
The `django-admin` tool provides the [`--template`][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.
## Contributing
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**][repo-gh]. This repository is also mirrored to [GitLab][repo-gl]
for demonstration purposes.
## License
This template is distributed under [The Unlicense][license] license. Projects
generated with this template may be distributed under different licenses.
[actions-badge]: https://github.com/laymonage/django-template-heroku/workflows/Test%20and%20Deploy/badge.svg
[commits-gh]: https://github.com/laymonage/django-template-heroku/commits/master
[pipeline-badge]: https://gitlab.com/laymonage/django-template-heroku/badges/master/pipeline.svg
[coverage-badge]: https://gitlab.com/laymonage/django-template-heroku/badges/master/coverage.svg
[commits-gl]: https://gitlab.com/laymonage/django-template-heroku/-/commits/master
[readme-id]: README.md
[heroku-dashboard]: https://dashboard.heroku.com
[djecrety]: https://djecrety.ir
[account-settings]: https://dashboard.heroku.com/account
[chromedriver]: https://chromedriver.chromium.org/downloads
[homebrew]: https://brew.sh
[ticket-21227]: https://code.djangoproject.com/ticket/21227
[bypass-cache]: https://en.wikipedia.org/wiki/Wikipedia:Bypass_your_cache
[flake8]: https://pypi.org/project/flake8
[pylint]: https://pypi.org/project/pylint
[black]: https://pypi.org/project/black
[isort]: https://pypi.org/project/isort
[template]: https://docs.djangoproject.com/en/3.1/ref/django-admin/#cmdoption-startproject-template
[repo-gh]: https://github.com/laymonage/django-template-heroku
[repo-gl]: https://gitlab.com/laymonage/django-template-heroku
[license]: LICENSE