Skip to content

Latest commit

 

History

History
347 lines (267 loc) · 13.8 KB

README.en.md

File metadata and controls

347 lines (267 loc) · 13.8 KB
Raw

django-template-heroku

Test and Deploy pipeline status coverage report

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.

Table of contents

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.

    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:

    venv\Scripts\activate

    On Linux/macOS:

    source venv/bin/activate

    If successful, there should be (venv) in your cmd/terminal prompt.

  4. Install Django in the virtual environment.

    python -m pip install Django

  5. 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.

  6. 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.

  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.

  9. 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.

  10. Turn your project directory into a Git repository and create an initial commit.

    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.

    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, please install the required packages with the following command.

    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.

    python manage.py migrate
python manage.py collectstatic

  15. After that, you can run your web server locally with the following command.

    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.

    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.

    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_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 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 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.

    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.
  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 or 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 and 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 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 would 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. This repository is also mirrored to GitLab for demonstration purposes.

License

This template is distributed under The Unlicense license. Projects generated with this template may be distributed under different licenses.