/in-for-a-penny

Code Instutite New Years Revolutions Hackaton

Primary LanguagePython

Dara Planner

Team Name: InForAPenny

Dara Planner

Contents(#contents)

User Experience

We considered enhanced quality of the experience when holidays and trips have been well thought out and planned. A good budget planning tool is a necessity. The Dara Planner tool was conceived to meet this requirement.

User stories

Epics were logged in the project issues under epics User stores were logged in the project issues under user stories

Technology:

  • Django
  • Materialize

Initially Tailwind CSS was chosen, as the frontend framework, however the implementation proved troublesome and the decision was made to switch to Materialize.

  • Python

    • Backend coding
  • Javascript, HTML, CSS

    • Frontend coding
  • Assorted IDEs

    • Intellij IDEA, Gitpod, GitLabs, VSCode

Initial MVP idea:

The team selected the idea of a budget planning tool from among a number of ideas discussed.

Actual idea & content:

The final project meets the requirement of providing a budgeting tool with support for multiple currencies.

User authentication and authorisation was included in the initial MVP, and was functional but has been excluded from the final product as there was insufficient time to properly style the register and login templates.

The application provides the following functionality

  • Budget planner with the following features
    • Budget base currency
    • Expense entries with individual currency settings
    • Budget total calculated in base currency
    • Budget creation/view/update/delete
  • Currency convertor allowing conversion of amount between two currencies
  • Useful travel link page

Design

Color Scheme:

<< detail your color palette here >>

Typography:

<< what font pairings did your team consider and pick? And why? >>

Imagery:

<< Detail imagery used to compliment your build & theme >>

<< ensure source attribution is maintained, and that you have used copyright free material >>

Wireframes:

- Mobile Wireframes:
- Desktop Wireframes:

Deployment

Development and Local Deployment

Environment

The development environment requires:

Artifact Download and installation instructions
git https://git-scm.com/downloads
Python https://www.python.org/downloads/
Django https://www.djangoproject.com/download/

Setup

Clone Repository

In an appropriate folder, run the following commands:

> git clone https://github.com/ibuttimer/in-for-a-penny.git
> cd in-for-a-penny

Alternatively, most IDEs provide an option to create a project from Version Control.

Virtual Environment

It is recommended that a virtual environment be used for development purposes. Please see Creating a virtual environment for details.

Note: Make sure to activate the virtual environment.

Python Setup

In the in-for-a-penny folder, run the following command to install the necessary python packages:

> pip install -r requirements-dev.txt
Production versus Development Setup

There are two requirements files:

Table 1: Configuration settings
Key Value
ENV_FILE If using an environment file, specifies the file to use. Defaults to .env in the project root folder.
PORT Port application is served on; default 8000
DEBUG A boolean that turns on/off debug mode; set to any of 'true', 'on', 'ok', 'y', 'yes', '1' to enable
DEVELOPMENT A boolean that turns on/off development mode; set to any of 'true', 'on', 'ok', 'y', 'yes', '1' to enable
TEST A boolean that turns on/off test mode; set to any of 'true', 'on', 'ok', 'y', 'yes', '1' to enable. Only valid when development mode is enabled.
SECRET_KEY Secret key for a particular Django installation. See Secret Key Generation
DATABASE_URL Database url
STORAGE_PROVIDER Storage provider from which to server static files; set to cloudinary (Cloudinary) or s3 (Amazon Simple Storage Service)
SITE_ID Id (primary key) of site in the django_site table of the database. See Configure authentication.
REMOTE_DATABASE_URL Url of remote PostgreSQL database resource. For an ElephantSQL database this is available from URL in the instance details.
Note: Only required for admin purposes, see database configuration under Cloud-based Deployment
Cloudinary-specific
CLOUDINARY_URL Cloudinary url
Amazon S3-specific
AWS_ACCESS_KEY_ID The access key for your AWS account.
AWS_SECRET_ACCESS_KEY The secret key for your AWS account.
AWS_STORAGE_BUCKET_NAME AWS S3 bucket name.
Heroku-specific
HEROKU_HOSTNAME Hostname of application on Heroku.
Note: To specify multiple hosts, use a comma-separated list with no spaces.
Note: Set to localhost,127.0.0.1 in local development mode

Environment variables

Set environment variables corresponding to the keys in Table 1: Configuration settings.

E.g.

For Linux and Mac:                       For Windows:
$ export DEVELOPMENT=true                > set DEVELOPMENT=true
Secret Key Generation

A convenient method of generating a secret key is to run the following command and copy its output.

$ python -c "import secrets; print(secrets.token_urlsafe())"

Before first run

Before running the application for the first time following cloning from the repository and setting up a new database, the following steps must be performed, from a terminal window, in the in-for-a-penny folder.

Initialise the database

$ python manage.py migrate

Create a superuser

Enter Username, Password and optionally Email address.

$ python manage.py createsuperuser

Configure authentication

From django-allauth Post-Installation

  • Add a Site for your domain in the database
    • Login to http://<domain>/admin/sites/site/ as the previously created superuser, e.g. http://127.0.0.1:8000/admin/sites/site/

    • Add a Site for your domain (django.contrib.sites app) or edit the default entry example.com.

      E.g.

      Domain name Display name
      localhost localhost

      Note: The id (primary key) of the site must be added to the application configuration. See SITE_ID in Table 1: Configuration settings.

Run server

In order to run the development server, run the following commands from the in-for-a-penny folder:

# start server
$ python manage.py runserver

By default, the server runs on port 8000 on the IP address 127.0.0.1. See runserver for details on passing an IP address and port number explicitly.

Cloud-based Deployment

Heroku

The site was deployed on Heroku.

Deployment

The following steps were followed to deploy the website:

  • Login to Heroku in a browser

  • From the dashboard select New -> Create new app

  • Set the value for App name, (e.g. dara-planner), choose the appropriate region and click Create app

  • To provision the application with a database, such as an ElephantSQL database.

  • From the app settings, select the Resources tab.

    • Under Add-ons add the following
      1. Cloudinary - Image and Video Management - Cloudinary Image & Video Tools

        Note: In order the access the dashboard for the provisioned Cloudinary account, use the Heroku CLI

        $ heroku addons:open cloudinary --app=dara-planner
  • From the app settings, select the Settings tab.

    • Under Buildpacks add the following buildpacks

      1. heroku/python
    • Under Config Vars add the following environment variables

      Key Value
      PORT 8000
      SECRET_KEY Secret key for a particular Django installation
      HEROKU_HOSTNAME Hostname of application on Heroku
      SITE_ID Id (primary key) of site in the django_site table of the database. See Configure authentication.
      The following keys are automatically added when Resources are provisioned:
      CLOUDINARY_URL Cloudinary url
      DATABASE_URL Database url
      - ElephantSQL database, copy the URL from the instance details page

See Table 1: Configuration settings for details.

If any other settings vary from the defaults outlined in Table 1: Configuration settings they must be added as well.

  • From the app settings, select the Deploy tab.

    • For the Deployment method, select GitHub and link the Heroku app to the GitHub repository.

      Note: To configure GitHub integration, you have to authenticate with GitHub. You only have to do this once per Heroku account. See GitHub Integration (Heroku GitHub Deploys).

    • Enable Automatic Deploys under Automatic deploys to enable automatic deploys from GitHub following a GitHub push if desired.

    • The application may also be deployed manually using Deploy Branch under Manual deploy

  • Initialise the database and Create a superuser

    Involves the same procedure as outlined in Initialise the database and Create a superuser but may be run from the local machine.

    • From a Development and Local Deployment

      • Initialise the database

        $ python manage.py migrate --database=remote
      • Create a superuser

        Enter Username, Password and optionally Email address.

        $ python manage.py createsuperuser --database=remote

      Note: Ensure to specify the --database=remote option to apply the change to the database specified by the REMOTE_DATABASE_URL environment variable.

    • Alternatively, the Heroku CLI may be utilised.

      After logging into the Heroku CLI in a terminal window, in the in-for-a-penny folder:

      • Initialise the database

        $  heroku run python manage.py migrate --app dara-planner
      • Create a superuser

        Enter Username, Password and optionally Email address.

        $ heroku run python manage.py createsuperuser --app dara-planner
  • Configure authentication

    Follow the same procedure as outlined in Configure authentication using the Heroku domain as <domain>, e.g. dara-planner.herokuapp.com

Render

The site was deployed on Render.

Deployment

The following steps were followed to deploy the website:

  • Login to Render in a browser

  • From the dashboard select New -> Web Service

  • Connect to the git repository

  • Set following

    • Name, (e.g. dara-planner)
    • Choose an appropriate region
    • Select the git branch to deploy
    • Select Python 3 runtime,
    • Set the Build command to ./build.sh
    • Set the Start command to gunicorn in_for_a_penny.wsgi:application
    • Select Create Web Service
  • To provision the application with a database, such as an ElephantSQL database.

  • Create an Amazon S3 bucket using Storing Django Static and Media Files on Amazon S3

  • Under Environment -> Environment Variables add the following environment variables

    Key Value
    PYTHON_VERSION Python version
    Note: At time of writing the Render Python3 environment does not include the necessary Python headers to compile the psycopg2 library for Python version 3.10.10, use Python version 3.9.16
    • Under Environment -> Secret Files add a file with the name .env with the following environment variables

      Key Value
      SECRET_KEY Secret key for a particular Django installation
      SITE_ID Id (primary key) of site in the django_site table of the database. See Configure authentication.
      DATABASE_URL Database url
      - ElephantSQL database, copy the URL from the instance details page
      STORAGE_PROVIDER Storage provider from which to server static files; set to s3 (Amazon Simple Storage Service)
      Amazon S3-specific
      AWS_ACCESS_KEY_ID The access key for your AWS account.
      AWS_SECRET_ACCESS_KEY The secret key for your AWS account.
      AWS_STORAGE_BUCKET_NAME AWS S3 bucket name.

See Table 1: Configuration settings for details.

If any other settings vary from the defaults outlined in Table 1: Configuration settings they must be added as well.

  • Select the Manual Deploy to deploy the application.

  • Initialise the database and Create a superuser

    Involves the same procedure as outlined in Initialise the database and Create a superuser but may be run from the local machine.

    • From a Development and Local Deployment

      • Initialise the database

        $ python manage.py migrate --database=remote
      • Create a superuser

        Enter Username, Password and optionally Email address.

        $ python manage.py createsuperuser --database=remote

      Note: Ensure to specify the --database=remote option to apply the change to the database specified by the REMOTE_DATABASE_URL environment variable.

  • Configure authentication

    Follow the same procedure as outlined in Configure authentication using the Heroku domain as <domain>, e.g. dara-planner.herokuapp.com

The live website is available at https://dara-planner.onrender.com

Testing

Manual testing was performed an all pages.

Credits

Code

Content

Media

Acknowledgements

Thank you to everyone for the effort and time contributed.