Update README and CONTRIBUTING
This commit is contained in:
parent
318571bb7e
commit
633c1e87e8
2 changed files with 163 additions and 111 deletions
|
|
@ -1,5 +1,36 @@
|
||||||
# Contributing
|
# Contributing to PKMN Trade Club
|
||||||
|
|
||||||
Thank you for help improving DjangoX. All kinds of contributions are welcome. Please note that this starter project is *intentionally* basic: I don't plan to add environment variables, Docker, or other production-appropriate features as I feel they will overwhelm beginners. But I'm open to suggestions!
|
Thank you for your interest in contributing to PKMN Trade Club! Your feedback, ideas, and contributions are vital to making this project even better. At this stage, we actively welcome issues and feature requests, and we may accept code contributions in the future.
|
||||||
|
|
||||||
Please submit an Issue or even better a PR and I'll review :)
|
## Ways to Contribute
|
||||||
|
|
||||||
|
There are several ways you can help:
|
||||||
|
|
||||||
|
- **Issues & Feature Requests:**
|
||||||
|
Found a bug or have an idea for a new feature? Please open an issue detailing the problem or your suggestion.
|
||||||
|
- Provide a clear and concise description.
|
||||||
|
- Include steps to reproduce the bug (if applicable).
|
||||||
|
- Share relevant environment details (OS, Python/Django versions, etc.).
|
||||||
|
- Attach any relevant logs or screenshots.
|
||||||
|
|
||||||
|
- **Documentation & Discussions:**
|
||||||
|
Contributions to documentation, tutorials, or discussions can have a great impact on our project's success. Feel free to suggest improvements or ask questions in the issues section.
|
||||||
|
|
||||||
|
## Code Style Guidelines
|
||||||
|
|
||||||
|
- Write clear, descriptive commit messages.
|
||||||
|
- Adhere to [PEP 8](https://www.python.org/dev/peps/pep-0008/) for Python code.
|
||||||
|
- Follow Django best practices for project structure, views, models, and templates.
|
||||||
|
- Ensure code changes are tested and documented.
|
||||||
|
|
||||||
|
## Communication
|
||||||
|
|
||||||
|
If you have questions or need assistance on how to contribute, please open an issue. We value a collaborative and respectful community, and your input is always welcome.
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
By contributing, you agree that your contributions will be licensed under the project's MIT License.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
Thank you for helping improve PKMN Trade Club!
|
||||||
|
|
|
||||||
237
README.md
237
README.md
|
|
@ -1,122 +1,143 @@
|
||||||
# Lithium: A Django-Powered Boilerplate
|
# PKMN Trade Club
|
||||||
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.
|
|
||||||
|
|
||||||
> This project was formerly known as _DjangoX_ but was renamed to _Lithium_ in November 2024.
|
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.
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
## Table of Contents
|
## Table of Contents
|
||||||
* **[Installation](#installation)**
|
|
||||||
* [Pip](#pip)
|
|
||||||
* [Docker](#docker)
|
|
||||||
* [Next Steps](#next-steps)
|
|
||||||
* [Contributing](#contributing)
|
|
||||||
* [Support](#support)
|
|
||||||
* [License](#license)
|
|
||||||
|
|
||||||
## 📖 Installation
|
- [PKMN Trade Club](#pkmn-trade-club)
|
||||||
Lithium can be installed via Pip or Docker. To start, clone the repo to your local computer and change into the proper directory.
|
- [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)
|
||||||
|
|
||||||
```
|
## Features
|
||||||
$ git clone https://github.com/wsvincent/lithium.git
|
|
||||||
$ cd lithium
|
- **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
|
## Deployment
|
||||||
You can use [pip](https://pypi.org/project/pip/) to create a fresh virtual environment on either Windows or macOS.
|
|
||||||
|
|
||||||
```
|
For production deployments consider these additional steps:
|
||||||
# On Windows
|
|
||||||
$ python -m venv .venv
|
|
||||||
$ Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
|
|
||||||
$ .venv\Scripts\Activate.ps1
|
|
||||||
(.venv) $
|
|
||||||
|
|
||||||
# On macOS
|
- **Production Server:** Use a web server like Gunicorn.
|
||||||
$ python -m venv .venv
|
- **Static Files:** Serve static files using Django’s WhiteNoise (or via a CDN).
|
||||||
$ source .venv/bin/activate
|
- **Fly.io Configuration:** A `fly.toml` file is provided if you wish to deploy on Fly.io.
|
||||||
(.venv) $
|
- **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
|
||||||
|
|
||||||
```
|
Contributions, feature requests, and issues are welcome! Please refer to [CONTRIBUTING.md](./CONTRIBUTING.md) for details on how to contribute to PKMN Trade Club.
|
||||||
(.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!
|
|
||||||
|
|
||||||
## License
|
## 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