Introduction

This is a full web app using Starlette.

This project exists with the help of some of really great tools.

• Starlette: Lightweight ASGI framework/toolkit for building async web services
• Tabler: UI kit based on Bootstrap 5
• SQLAlchemy: The Python SQL Toolkit and Object Relational Mapper
• Arq: Job queues and RPC in python with asyncio and redis
• SQLAdmin: Admin interface for SQLAlchemy models
• Authlib: The ultimate Python library in building OAuth and OpenID Connect servers
• And more...

Screenshots

Home Page

Login Page

Register Page

Forgot Password Page

User Profile Setting Page

Setup

Requirements

• Python: at least version 3.10
• Database: SQLite, MySQL, PostgresQL or anything that is supported by SQLAlchemy
• Redis
• SMTP
• OAuth2 (GitHub and Google)

Application Configuration

Application configuration is required as on .env.example. You can copy this file as .env and edit it as you want.

cp .env.example .env

Process Files Directories

mkdir -p files/{logs,pids}

Database

SQLite

Additional requirements

aiosqlite

.env

DATABASE_URL=sqlite+aiosqlite:///./sqlite.db

MySQL

Additional requirements

aiomysql
PyMySQL

.env

DATABASE_URL=mysql+aiomysql://USER:[email protected]/DATABASE_NAME

PostgresQL

Additional requirements

asyncpg

.env

DATABASE_URL=postgresql+asyncpg://USER:[email protected]/DATABASE_NAME

Create Tables

# Initialisation
mkdir alembic/versions

# Generate migration scripts
alembic revision --autogenerate -m 'initial'
# Run first migration
alembic upgrade head

Add New Model Table

After create new DB model, make sure it has been imported on apps.core.db_tables, then run:

# Generate migration scripts
alembic revision --autogenerate -m 'initial'
# Run first migration
alembic upgrade head

Redis

Redis is required for arq for job queues and RPC in python with asyncio and redis.

See Redis: Arq section on the .env file.

SMTP

Upon registration, password update, reset password action, you need to open links that sent to your email.

White starting this web application, you can use a really cool fake SMTP service that provided by Ethereal Email.

For production use, you may edit the SMTP configuration on the .env file for any SMTP service you like.

See SMTP: Email section on the .env file.

Admin User

On first startup, an admin user is created. The credentials should be placed on .env file.

Admin configuration example on .env file

ADMIN_USERNAME=admin
ADMIN_PASSWORD=password
ADMIN_EMAIL='admin@localhost'

OAuth2

This web app is extended to use third party Oauth2 provider such as Google and GitHub. We need to set up OAuth2 configuration one .env.

GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=

Please make sure to set the scopes for the OAuth2 clients for at least to be able to see email and public profile.

Run Locally (Development Mode)

Update .env

ENV=dev

Web Application Service

bash scripts/dev.sh

Arq (Job Queueing and Processing)

bash scripts/arq.sh

Run In Production

For production use, make sure you edit the .env configuration file, such as. Make sure you use proper value for SECRET_KEY and admin user credentials.

ENV=prod
SECRET_KEY=CHANGE THIS SECRET

ADMIN_USERNAME=admin
ADMIN_PASSWORD=password
ADMIN_EMAIL='admin@localhost'

Then make sure you use a real SMTP Provided and edit the SMTP configuration.

Web Application Service

bash scripts/prod.sh

Kill the services

kill `cat files/pids/web_app.pid`

Arq (Job Queueing and Processing)

bash scripts/arq.sh

Nginx

Please take a look on configs/nginx_conf_d_yousite.conf. Copy that file and edit on /etc/nginx/conf.d/yoursite_com.conf.

SSL Certificate

Please consider to create a free SSH Certificate you your web app. :)

Letsencrypt will help you to run your web application to this.

Test

Install Test Packages

pip install -r requirements/test.txt

Run Test

pytest

Changes

2023-10-27

• Update README for missing starting instruction

2023-10-24

• Remove usage of arq-dashboard.
  Remove arq-dashboard by running pip uninstall arq-dashboard command to be able to update to current version