Update README and CONTRIBUTING
This commit is contained in:
parent
318571bb7e
commit
633c1e87e8
2 changed files with 163 additions and 111 deletions
237
README.md
237
README.md
|
|
@ -1,122 +1,143 @@
|
|||
# Lithium: A Django-Powered Boilerplate
|
||||
Lithium is a batteries-included Django starter project with everything you need to start coding, including user authentication, static files, default styling, debugging, DRY forms, custom error pages, and more.
|
||||
# PKMN Trade Club
|
||||
|
||||
> This project was formerly known as _DjangoX_ but was renamed to _Lithium_ in November 2024.
|
||||
|
||||
https://github.com/wsvincent/djangox/assets/766418/a73ea730-a7b4-4e53-bf51-aa68f6816d6a
|
||||
|
||||
## 👋 Free Newsletter
|
||||
[Sign up for updates](https://buttondown.com/lithiumsaas) to the free and upcoming premium SaaS version!
|
||||
|
||||
## 🚀 Features
|
||||
|
||||
- Django 5.1 & Python 3.12
|
||||
- Installation via [Pip](https://pypi.org/project/pip/) or [Docker](https://www.docker.com/)
|
||||
- User authentication--log in, sign up, password reset--via [django-allauth](https://github.com/pennersr/django-allauth)
|
||||
- Static files configured with [Whitenoise](http://whitenoise.evans.io/en/stable/index.html)
|
||||
- Styling with [Bootstrap v5](https://getbootstrap.com/)
|
||||
- Debugging with [django-debug-toolbar](https://github.com/jazzband/django-debug-toolbar)
|
||||
- DRY forms with [django-crispy-forms](https://github.com/django-crispy-forms/django-crispy-forms)
|
||||
- Custom 404, 500, and 403 error pages
|
||||
PKMN Trade Club is a Django-powered application built to connect Pokémon TCG Pocket trading enthusiasts in a secure, scalable, and community-driven environment. This platform leverages Django’s robust features and stability, a modular project structure, and best practices to deliver a smooth trading experience.
|
||||
|
||||
## Table of Contents
|
||||
* **[Installation](#installation)**
|
||||
* [Pip](#pip)
|
||||
* [Docker](#docker)
|
||||
* [Next Steps](#next-steps)
|
||||
* [Contributing](#contributing)
|
||||
* [Support](#support)
|
||||
* [License](#license)
|
||||
|
||||
## 📖 Installation
|
||||
Lithium can be installed via Pip or Docker. To start, clone the repo to your local computer and change into the proper directory.
|
||||
- [PKMN Trade Club](#pkmn-trade-club)
|
||||
- [Table of Contents](#table-of-contents)
|
||||
- [Features](#features)
|
||||
- [Installation](#installation)
|
||||
- [Local Development](#local-development)
|
||||
- [Docker Deployment](#docker-deployment)
|
||||
- [Configuration](#configuration)
|
||||
- [Database](#database)
|
||||
- [Running Tests](#running-tests)
|
||||
- [Deployment](#deployment)
|
||||
- [Contributing](#contributing)
|
||||
- [License](#license)
|
||||
|
||||
```
|
||||
$ git clone https://github.com/wsvincent/lithium.git
|
||||
$ cd lithium
|
||||
## Features
|
||||
|
||||
- **Django & Python**: Built with Django 5.1 and Python 3.12.
|
||||
- **Modular Architecture**: Separate Django apps for trades, accounts, cards, and more.
|
||||
- **User Authentication**: Comprehensive authentication powered by Django Allauth.
|
||||
- **Responsive UI**: Custom theming with Tailwind CSS, DaisyUI, and AlpineJS.
|
||||
- **Production-Ready**: Docker and PostgreSQL configuration for scalable deployments.
|
||||
- **Development Tools**: Built-in support for migrations, testing, and seeding initial data.
|
||||
- **Security & Performance**: Carefully configured for deployment with production best practices.
|
||||
|
||||
## Installation
|
||||
|
||||
### Local Development
|
||||
|
||||
1. **Clone the repository:**
|
||||
|
||||
```bash
|
||||
git clone https://git.badblocks.dev/badbl0cks/pkmntrade.club.git
|
||||
cd pkmntrade.club
|
||||
```
|
||||
|
||||
2. **Install dependencies via uv:**
|
||||
|
||||
```bash
|
||||
uv pip install -r requirements.txt
|
||||
```
|
||||
|
||||
3. **Configure environment variables:**
|
||||
|
||||
Copy the example environment file and update credentials as needed:
|
||||
|
||||
```bash
|
||||
cp .env .env.production
|
||||
```
|
||||
|
||||
4. **Apply migrations and seed initial data:**
|
||||
|
||||
```bash
|
||||
python manage.py migrate
|
||||
python manage.py createsuperuser
|
||||
python manage.py createcachetable django_cache
|
||||
```
|
||||
|
||||
5. **Start the development server:**
|
||||
|
||||
```bash
|
||||
uv run manage.py runserver
|
||||
```
|
||||
|
||||
Visit [http://127.0.0.1:8000](http://127.0.0.1:8000) in your browser.
|
||||
|
||||
### Docker Deployment
|
||||
|
||||
1. **Build and run containers:**
|
||||
|
||||
```bash
|
||||
docker-compose up -d --build
|
||||
```
|
||||
|
||||
2. **Run migrations and create a superuser inside the container:**
|
||||
|
||||
```bash
|
||||
docker-compose exec web python manage.py migrate
|
||||
docker-compose exec web python manage.py createsuperuser
|
||||
docker-compose exec web python manage.py createcachetable django_cache
|
||||
```
|
||||
|
||||
3. **Access the site:**
|
||||
|
||||
Open [http://127.0.0.1:8000](http://127.0.0.1:8000)
|
||||
|
||||
## Configuration
|
||||
|
||||
- **Environment Variables:**
|
||||
Manage your local vs. production settings using `.env` and `.env.production`. Update these to match your database credentials, secret keys, and other configurations.
|
||||
|
||||
- **Django Settings:**
|
||||
Production settings are in `django_project/settings.py`.
|
||||
|
||||
- **Database Settings:**
|
||||
Example configuration for PostgreSQL:
|
||||
|
||||
```python
|
||||
DATABASES = {
|
||||
'default': {
|
||||
'ENGINE': 'django.db.backends.postgresql',
|
||||
'NAME': 'postgres',
|
||||
'USER': 'postgres',
|
||||
'PASSWORD': 'postgres',
|
||||
'HOST': 'db', # as defined in docker-compose.yml
|
||||
'PORT': 5432,
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Database
|
||||
|
||||
The platform uses PostgreSQL as its primary database in production. For local development, you may use SQLite or configure PostgreSQL by updating your settings and environment variables as needed.
|
||||
|
||||
## Running Tests
|
||||
|
||||
Run Django’s testing suite with:
|
||||
|
||||
```bash
|
||||
python manage.py test
|
||||
```
|
||||
|
||||
### Pip
|
||||
You can use [pip](https://pypi.org/project/pip/) to create a fresh virtual environment on either Windows or macOS.
|
||||
## Deployment
|
||||
|
||||
```
|
||||
# On Windows
|
||||
$ python -m venv .venv
|
||||
$ Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
|
||||
$ .venv\Scripts\Activate.ps1
|
||||
(.venv) $
|
||||
For production deployments consider these additional steps:
|
||||
|
||||
# On macOS
|
||||
$ python -m venv .venv
|
||||
$ source .venv/bin/activate
|
||||
(.venv) $
|
||||
```
|
||||
- **Production Server:** Use a web server like Gunicorn.
|
||||
- **Static Files:** Serve static files using Django’s WhiteNoise (or via a CDN).
|
||||
- **Fly.io Configuration:** A `fly.toml` file is provided if you wish to deploy on Fly.io.
|
||||
- **Deployment Scripts:** Use `deploy.sh` for automated deployment tasks.
|
||||
- **Security & Email:** Update `DEFAULT_FROM_EMAIL`, `ALLOWED_HOSTS`, and other security settings in `django_project/settings.py`.
|
||||
|
||||
Then install all packages hosted in `requirements.txt` and run `migrate` to configure the initial database. The command `createsuperuser` will create a new superuser account for accessing the admin. Execute the `runserver` commandt o start up the local server.
|
||||
## Contributing
|
||||
|
||||
```
|
||||
(.venv) $ pip install -r requirements.txt
|
||||
(.venv) $ python manage.py migrate
|
||||
(.venv) $ python manage.py createsuperuser
|
||||
(.venv) $ python manage.py runserver
|
||||
# Load the site at http://127.0.0.1:8000 or http://127.0.0.1:8000/admin for the admin
|
||||
```
|
||||
|
||||
### Docker
|
||||
|
||||
To use Docker with PostgreSQL as the database update the `DATABASES` section of `django_project/settings.py` to reflect the following:
|
||||
|
||||
```python
|
||||
# django_project/settings.py
|
||||
DATABASES = {
|
||||
"default": {
|
||||
"ENGINE": "django.db.backends.postgresql",
|
||||
"NAME": "postgres",
|
||||
"USER": "postgres",
|
||||
"PASSWORD": "postgres",
|
||||
"HOST": "db", # set in docker-compose.yml
|
||||
"PORT": 5432, # default postgres port
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The `INTERNAL_IPS` configuration in `django_project/settings.py` must be also be updated:
|
||||
|
||||
```python
|
||||
# config/settings.py
|
||||
# django-debug-toolbar
|
||||
import socket
|
||||
hostname, _, ips = socket.gethostbyname_ex(socket.gethostname())
|
||||
INTERNAL_IPS = [ip[:-1] + "1" for ip in ips]
|
||||
```
|
||||
|
||||
And then proceed to build the Docker image, run the container, and execute the standard commands within Docker.
|
||||
|
||||
```
|
||||
$ docker compose up -d --build
|
||||
$ docker compose exec web python manage.py migrate
|
||||
$ docker compose exec web python manage.py createsuperuser
|
||||
# Load the site at http://127.0.0.1:8000 or http://127.0.0.1:8000/admin for the admin
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Add environment variables. There are multiple packages but I personally prefer [environs](https://pypi.org/project/environs/).
|
||||
- Add [gunicorn](https://pypi.org/project/gunicorn/) as the production web server.
|
||||
- Update the [EMAIL_BACKEND](https://docs.djangoproject.com/en/4.0/topics/email/#module-django.core.mail) and connect with a mail provider.
|
||||
- Make the [admin more secure](https://opensource.com/article/18/1/10-tips-making-django-admin-more-secure).
|
||||
- `django-allauth` supports [social authentication](https://django-allauth.readthedocs.io/en/latest/providers.html) if you need that.
|
||||
|
||||
I cover all of these steps in tutorials and premium courses over at [LearnDjango.com](https://learndjango.com).
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
Contributions, issues and feature requests are welcome! See [CONTRIBUTING.md](https://github.com/wsvincent/djangox/blob/master/CONTRIBUTING.md).
|
||||
|
||||
## ⭐️ Support
|
||||
|
||||
Give a ⭐️ if this project helped you!
|
||||
Contributions, feature requests, and issues are welcome! Please refer to [CONTRIBUTING.md](./CONTRIBUTING.md) for details on how to contribute to PKMN Trade Club.
|
||||
|
||||
## License
|
||||
|
||||
[The MIT License](LICENSE)
|
||||
This project is licensed under the MIT License. See [LICENSE](./LICENSE) for more information.
|
||||
Loading…
Add table
Add a link
Reference in a new issue