badblocks/pkmntrade.club
1
1
Fork 0
Code Issues 14 Pull requests Projects 1 Releases Packages Wiki Activity

Update README and CONTRIBUTING

Browse source
This commit is contained in:
badblocks 2025-04-16 23:27:27 -07:00
parent 318571bb7e
commit 633c1e87e8
2 changed files with 163 additions and 111 deletions
Download patch file Download diff file Expand all files Collapse all files

37
CONTRIBUTING.md
View file

@ -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!

203
README.md
View file

@ -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
```
### Pip
You can use [pip](https://pypi.org/project/pip/) to create a fresh virtual environment on either Windows or macOS.
2. **Install dependencies via uv:**
```
# On Windows
$ python -m venv .venv
$ Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
$ .venv\Scripts\Activate.ps1
(.venv) $
# On macOS
$ python -m venv .venv
$ source .venv/bin/activate
(.venv) $
```bash
uv pip install -r requirements.txt
```
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.
3. **Configure environment variables:**
```
(.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
Copy the example environment file and update credentials as needed:
```bash
cp .env .env.production
```
### Docker
4. **Apply migrations and seed initial data:**
To use Docker with PostgreSQL as the database update the `DATABASES` section of `django_project/settings.py` to reflect the following:
```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
# 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
'default': {
'ENGINE': 'django.db.backends.postgresql',
'NAME': 'postgres',
'USER': 'postgres',
'PASSWORD': 'postgres',
'HOST': 'db', # as defined in docker-compose.yml
'PORT': 5432,
}
}
```
The `INTERNAL_IPS` configuration in `django_project/settings.py` must be also be updated:
## Database
```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]
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
```
And then proceed to build the Docker image, run the container, and execute the standard commands within Docker.
## Deployment
```
$ 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
```
For production deployments consider these additional steps:
## Next Steps
- **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`.
- 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.
## Contributing
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.