Portfolio: a showcase and commission website

Portfolio is a dynamic website showcasing my projects, with commissioning functionality, made for Code Institute's 5th submission project.

A live version is deployed and available here.

Important notes

The documentation is split across three files:

README.md (this file): Overview of the project. Read this to get an idea of the basic concept, technologies used and project conventions.
DESIGN.md: UX design notes crafted during early stages of development. The design process is described entirely, from the concept and market research, through information structuring to visual design principles and color palettes.
TESTING.md: Automated and manual testing procedures are described in detail, as well as their outcomes.

The project is managed via a GitHub project. Issues are created in a "User story" format, and assigned size/complexity and importance. Each issue contains a title, user story sentence, and a list of technical expectations.

Highlights

The homepage features an attractive eye-catch figure.

Further down, the page showcases past projects, serving as a portfolio.

Further still, testimonials of real existing users are shown (if existing.)

After signing in, users can access their dashboard with all commissions so far.

Commissions can be paid for using an online gateway.

Email notifications are sent to the website owner and/or project owner when relevant.

Technologies used

Python 3: Used for the backend portion of the app,
HTML5+CSS3: Design of the frontend,
Javascript (ES6): Interactive functionality, payment gateway, advanced page layout,
Stripe API: card payment functionality,
SMTP: Sending emails from the app.

Dependencies

All dependencies are included, or installed via requirements.txt.

Django 4.1: Backend framework used to serve the app to the browser and as a RESTful interface to manipulate the models,
Bootstrap Reboot: A CSS reset with sane basic styles,
django-allauth: Django library that expands on the built-in user authentication,
django-countries: Django library that adds a country model field and form widget,
gunicorn: A production-ready application server,
psycopg2: The most popular Postgres driver for Python,
python-dotenv: Used to handle environment variables more easily,
stripe: Library for interacting with the public Stripe API.

Deployment

Portfolio is a Django web-app, and is deployed via the standard Django procedures. A number of settings is exposed via environment variables, some of which must be set for the app to load:

PORTFOLIO_SECRET_KEY: required. Must be set to any string, as long as it's kept secret. Make sure the key is not present in committed code, logs, etc.
PORTFOLIO_STRIPE_PUBLISHABLE_KEY, PORTFOLIO_STRIPE_SECRET_KEY, PORTFOLIO_STRIPE_WEBHOOK_SECRET: set of keys obtained from Stripe. The webhook must be configured under the /account/webhook/ URL.
PORTFOLIO_EMAIL_HOST, PORTFOLIO_EMAIL_USER, PORTFOLIO_EMAIL_PASSWORD, PORTFOLIO_EMAIL_PORT: SMTP server details for sending emails through,
PORTFOLIO_POSTGRES_PASSWORD: password to the Postgres database.

Deployment example

Portfolio can be deployed via a number of methods - to a dedicated server, application platform such as S3 or Heroku, a Docker container, etc. The instance above was deployed to a virtual environment (venv) in a dedicated server. The procedure will be detailed below for reference. Creating accounts on email providers and Stripe are well documented on their own help pages, and outside of the scope of this section.

Prerequisites:

Server is running a Linux distribution with systemd,
Nginx is installed and running,
PostgreSQL is installed and running.

Navigate to the destination folder that will store the application, such as /srv/http,

Clone the repository:

git clone https://github.com/Tearnote/portfolio

We need to set up a virtual environment for Python. Enter the cloned project, and create a fresh virtualenv:
```
python -m venv venv
```
Activate the virtual environment in current shell. This should add (venv) to your visible command line:
```
source venv/bin/activate
```
Dependencies can now be installed with the following command:
```
pip install -r requirements.txt
```
The dependencies include Gunicorn and Psycopg2, which will be required for a production deployment. Gunicorn will need to be configured separately to match your deployment. An example configuration file is included here. Copy this to the root folder of the project, and customize it with your server's paths.
We will now configure the database. Portfolio is by default configured to use a Sqlite database file, which is only suitable for a test deployment with few concurrent users. Configure your Postgres connection in portfolio/settings.py. An example commented-out configuration is included.

The database and user needs to be created on Postgres side. These example commands will configure the database for use, customize them to match your deployment:

sudo -u postgres psql
create database portfolio;
create user portfolio with password 'portfolio';
alter role portfolio set client_encoding to 'utf8';
alter role portfolio set default_transaction_isolation to 'read committed';
alter role portfolio set timezone to 'UTC';
grant all privileges on database portfolio to portfolio;
\q

You should now have all the prerequisites to get the webapp to run. To populate all the environment variables, the definitions can be inserted in the .env file in the root of the project.
Now, you should be able to connect to the database to create all the required tables. Navigate to the project folder, activate the venv again if needed (step 4.), and run the following commands:
```
python manage.py makemigrations
python manage.py migrate
```
Optionally, you might want to configure Portfolio as a systemd service so that it's started automatically. An example systemd unit file is available here. Customize the file with your credentials and paths, drop it into /etc/systemd/system/, and run these commands to reload unit files and start Portfolio:
```
sudo systemctl daemon-reload
sudo systemctl start portfolio
```
If the unit doesn't start correctly, look for errors in the system journal and the Gunicorn log file as configured in gunicorn.conf.py (step 6.)
The app is now running, and it's time to expose it to the world via Nginx reverse proxy. This needs to be configured to match your domain name, serving methods and SSL setup, among others. You can find an example Nginx configuration file here, which needs to be customized with domain names and local paths. The file assumes the app is hosted on localhost:8002, which matches the example Gunicorn configuration file.
You should be able to view the app via its URL, but the styles and images will not work. For that, static files must be hosted via Nginx. Collect all static files by navigating to the project folder, activating the venv (step 4.), and running the following command:
```
python manage.py portfoliotstatic
```
This will copy all static files into the static folder in the project. The default Nginx configuration will serve these files directly.
For mailing list functionality, customize the hardcoded Mailchimp widget in home/templates/home/index.html with code generated from the Mailchimp control panel.

Bugs

None that were found remain in the submitted site.

Credits

The vendor directory contains frontend code from other parties.

templates/allauth contains majorly templates that were copied from the allauth library for customization.

All other non-original code is attributed inline.

Tearnote / portfolio