https://github.com/jockerz/starlettestarter
Starlette web application starter. Ready with Register, Login, Forgot Password, Setting and more pages.
https://github.com/jockerz/starlettestarter
arq asgi sqlalchemy starlette tabler
Last synced: 10 months ago
JSON representation
Starlette web application starter. Ready with Register, Login, Forgot Password, Setting and more pages.
- Host: GitHub
- URL: https://github.com/jockerz/starlettestarter
- Owner: jockerz
- License: mit
- Created: 2023-03-23T16:46:42.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2024-11-13T10:50:07.000Z (over 1 year ago)
- Last Synced: 2024-11-13T11:35:24.532Z (over 1 year ago)
- Topics: arq, asgi, sqlalchemy, starlette, tabler
- Language: JavaScript
- Homepage:
- Size: 5.37 MB
- Stars: 5
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Frontend Choice : _Tabler_ | [AdminLTE](https://github.com/jockerz/StarletteStarter/tree/adminlte)
# Introduction
This is a full web app using [Starlette][Starlette].
This project exists with the help of some of really great tools.
- [Starlette][Starlette]: Lightweight ASGI framework/toolkit
for building async web services
- [Tabler][Tabler]: UI kit based on Bootstrap 5
- [SQLAlchemy][SQLAlchemy]: The Python SQL Toolkit and Object Relational Mapper
- [Arq][arq]: Job queues and RPC in python with asyncio and redis
- [SQLAdmin][SQLAdmin]: Admin interface for SQLAlchemy models
- [Authlib][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][SQLAlchemy]
- Redis
- SMTP
- OAuth2 (GitHub and Google)
## Clone the Repository
```sh
git clone --depth=1 https://github.com/jockerz/StarletteStarter
```
## Application Configuration
Application configuration is required as on `.env.example`.
You can copy this file as `.env` and edit it as you want.
```shell
cp .env.example .env
```
## Process Files Directories
```shell
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:PASSWORD@127.0.0.1/DATABASE_NAME
```
### PostgresQL
Additional requirements
```
asyncpg
```
`.env`
```
DATABASE_URL=postgresql+asyncpg://USER:PASSWORD@127.0.0.1/DATABASE_NAME
```
## Install Python Modules
```sh
# Create Virtualenv
virtualenv -ppython3 venv
# Activate virtualenv
source venv/bin/activate
# Install modules
pip install -r requirements/apps.txt
```
### Create Tables
```bash
# 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:
```bash
# Generate migration scripts
alembic revision --autogenerate -m 'initial'
# Run first migration
alembic upgrade head
```
## Translations
### Extract Localizable Messages
```shell
bash scripts/transation.sh extract
```
### Update Translation Files
```shell
bash scripts/transation.sh update
```
### Compile Translation Files
```shell
bash scripts/transation.sh compile
```
## Redis
Redis is required for [`arq`][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][ethereal].
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
```text
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`.
```text
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`
```text
ENV=dev
```
## Web Application Service
```shell
bash scripts/dev.sh
```
## Arq (Job Queueing and Processing)
```shell
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.
```text
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
```shell
bash scripts/prod.sh
```
## Kill the services
```shell
kill `cat files/pids/web_app.pid`
```
## Arq (Job Queueing and Processing)
```shell
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][Letsencrypt] will help you to run your web application to this.
# Test
## Install Test Packages
```shell
pip install -r requirements/test.txt
```
## Run Test
```shell
pytest
```
# Changes
## 2025-05-06
- Add new branch [AdminLTE](https://github.com/jockerz/StarletteStarter/tree/adminlte)
## 2024-11-8
- Python library updated
- [Arq-dashboard](arq-dashboard) still not working
Remove it later
## 2023-10-27
- Update __README__ for missing starting instruction
## 2023-10-24
- Remove usage of [arq-dashboard][arq-dashboard].
Remove `arq-dashboard` by running `pip uninstall arq-dashboard` command
to be able to update to current version
[arq]: https://arq-docs.helpmanual.io
[arq-dashboard]: https://github.com/ninoseki/arq-dashboard
[authlib]: https://authlib.org
[ethereal]: https://ethereal.email
[Letsencrypt]: https://letsencrypt.org
[SQLAdmin]: https://aminalaee.dev/sqladmin
[SQLAlchemy]: https://docs.sqlalchemy.org/en/20/
[Starlette]: https://www.starlette.io
[Tabler]: https://tabler.io