robert/ttrpg-initiative-tracker
1
0
Fork 0
Code Pull Requests Releases 2 Wiki Activity

More readme cleanup.

Browse Source
This commit is contained in:
Robert Johnson
2025-05-26 10:31:04 -04:00
parent c6cb37835f
commit 42d70f0817
1 changed files with 98 additions and 75 deletions
Download Patch File Download Diff File Expand all files Collapse all files

173
README.md
View File

@ -1,5 +1,9 @@
# TTRPG Initiative Tracker
This application is the result of not having the exact tool I want to use, and a few sessions of [vibe-coding](https://www.youtube.com/watch?v=Tw18-4U7mts) with [Google Gemini](https://developers.google.com/gemini-code-assist/docs/overview).
**Use at your own risk.**
A web-based application designed to help Dungeon Masters (DMs) manage and display combat initiative for tabletop role-playing games (TTRPGs). It features a DM admin interface for controlling encounters and a separate player display view suitable for an external monitor or for players to view on their own devices.
## Features
@ -70,62 +74,62 @@ This flow allows the DM to prepare and run encounters efficiently while providin
### Local Development Setup (using npm)
1. **Clone the Repository:**
```bash
git clone <your-repository-url>
cd ttrpg-initiative-tracker
#### **Clone the Repository:**
```bash
git clone <your-repository-url>
cd ttrpg-initiative-tracker
```
#### **Create Firebase Configuration File (`.env.local`):**
* In the root of the project, create a file named `.env.local`.
* Add your Firebase project configuration details to this file. You can find these in your Firebase project settings (Project settings > General > Your apps > Firebase SDK snippet > Config).
* **Important:** This `.env.local` file contains sensitive API keys and should **NOT** be committed to Git. Make sure it's listed in your `.gitignore` file.
Your `.env.local` should look like this:
```ini
REACT_APP_FIREBASE_API_KEY="YOUR_FIREBASE_API_KEY"
REACT_APP_FIREBASE_AUTH_DOMAIN="YOUR_FIREBASE_AUTH_DOMAIN"
REACT_APP_FIREBASE_PROJECT_ID="YOUR_FIREBASE_PROJECT_ID"
REACT_APP_FIREBASE_STORAGE_BUCKET="YOUR_FIREBASE_STORAGE_BUCKET"
REACT_APP_FIREBASE_MESSAGING_SENDER_ID="YOUR_FIREBASE_MESSAGING_SENDER_ID"
REACT_APP_FIREBASE_APP_ID="YOUR_FIREBASE_APP_ID"
# Used for namespacing Firestore paths, can be any unique string for your app instance
REACT_APP_TRACKER_APP_ID="ttrpg-initiative-tracker-dev"
```
*An `.env.example` file is included in the repository as a template.*
#### **Install Dependencies:**
Navigate to the project root in your terminal and run:
```bash
npm install
```
This will install all the necessary packages defined in `package.json` and create a `package-lock.json` file.
#### **Set up Firestore Security Rules:**
* Go to your Firebase project console -> Firestore Database -> Rules.
* Use the following rules for development (allows authenticated users to read/write all data). **For production, you MUST implement more restrictive rules.**
```
2. **Create Firebase Configuration File (`.env.local`):**
* In the root of the project, create a file named `.env.local`.
* Add your Firebase project configuration details to this file. You can find these in your Firebase project settings (Project settings > General > Your apps > Firebase SDK snippet > Config).
* **Important:** This `.env.local` file contains sensitive API keys and should **NOT** be committed to Git. Make sure it's listed in your `.gitignore` file.
Your `.env.local` should look like this:
```ini
REACT_APP_FIREBASE_API_KEY="YOUR_FIREBASE_API_KEY"
REACT_APP_FIREBASE_AUTH_DOMAIN="YOUR_FIREBASE_AUTH_DOMAIN"
REACT_APP_FIREBASE_PROJECT_ID="YOUR_FIREBASE_PROJECT_ID"
REACT_APP_FIREBASE_STORAGE_BUCKET="YOUR_FIREBASE_STORAGE_BUCKET"
REACT_APP_FIREBASE_MESSAGING_SENDER_ID="YOUR_FIREBASE_MESSAGING_SENDER_ID"
REACT_APP_FIREBASE_APP_ID="YOUR_FIREBASE_APP_ID"
# Used for namespacing Firestore paths, can be any unique string for your app instance
REACT_APP_TRACKER_APP_ID="ttrpg-initiative-tracker-dev"
```
*An `.env.example` file is included in the repository as a template.*
3. **Install Dependencies:**
Navigate to the project root in your terminal and run:
```bash
npm install
```
This will install all the necessary packages defined in `package.json` and create a `package-lock.json` file.
4. **Set up Firestore Security Rules:**
* Go to your Firebase project console -> Firestore Database -> Rules.
* Use the following rules for development (allows authenticated users to read/write all data). **For production, you MUST implement more restrictive rules.**
```
rules_version = '2';
service cloud.firestore {
match /databases/{database}/documents {
match /{document=**} {
allow read, write: if request.auth != null;
}
}
rules_version = '2';
service cloud.firestore {
match /databases/{database}/documents {
match /{document=**} {
allow read, write: if request.auth != null;
}
```
* Publish these rules.
5. **Enable Anonymous Authentication:**
* In your Firebase project console -> Authentication -> Sign-in method.
* Enable "Anonymous" as a sign-in provider.
6. **Run the Development Server:**
```bash
npm start
}
}
```
This will start the React development server, usually on `http://localhost:3000`. The application will open in your default web browser.
* Publish these rules.
#### **Enable Anonymous Authentication:**
* In your Firebase project console -> Authentication -> Sign-in method.
* Enable "Anonymous" as a sign-in provider.
#### **Run the Development Server:**
```bash
npm start
```
This will start the React development server, usually on `http://localhost:3000`. The application will open in your default web browser.
### Deployment with Docker
@ -134,39 +138,58 @@ This project includes a `Dockerfile` to containerize the application for deploym
* **Stage 2 (nginx):** Uses an Nginx server to serve the static files produced in the build stage.
**1. Prerequisites for Docker:**
* Ensure Docker Desktop (or Docker Engine on Linux) is installed and running. Download from [docker.com](https://www.docker.com/products/docker-desktop).
* Ensure Docker Desktop (or Docker Engine on Linux) is installed and running. Download from [docker.com](https://www.docker.com/products/docker-desktop).
**2. Building the Docker Image (for Local Testing with `.env.local`):**
* Make sure your `.env.local` file is present in the project root and correctly configured with your Firebase details. The `Dockerfile` is set up to copy this file as `.env` during the build for local testing.
* **Security Warning:** The image built this way will contain your Firebase API keys from `.env.local`. **Do NOT push this specific image to a public Docker registry.** For production, environment variables should be injected by your hosting platform or CI/CD pipeline at build or runtime.
* Make sure your `.env.local` file is present in the project root and correctly configured with your Firebase details. The `Dockerfile` is set up to copy this file as `.env` during the build for local testing.
* **Security Warning:** The image built this way will contain your Firebase API keys from `.env.local`. **Do NOT push this specific image to a public Docker registry.** For production, environment variables should be injected by your hosting platform or CI/CD pipeline at build or runtime.
To build the image, navigate to the project root and run:
```bash
docker build -t ttrpg-initiative-tracker .
```
*(You can replace `ttrpg-initiative-tracker` with your preferred image name/tag).*
To build the image, navigate to the project root and run:
```bash
docker build -t ttrpg-initiative-tracker .
```
*(You can replace `ttrpg-initiative-tracker` with your preferred image name/tag).*
**3. Running the Docker Container Locally:**
Once the image is built, run it:
```bash
docker run -p 8080:80 --rm --name ttrpg-tracker-app ttrpg-initiative-tracker
```
* `-p 8080:80`: Maps port 8080 on your host machine to port 80 inside the container (where Nginx is listening).
* `--rm`: Automatically removes the container when it stops.
* `--name ttrpg-tracker-app`: Assigns a name to the running container.
* `ttrpg-initiative-tracker`: The name of the image you built.
Once the image is built, run it:
```bash
docker run -p 8080:80 --rm --name ttrpg-tracker-app ttrpg-initiative-tracker
```
* `-p 8080:80`: Maps port 8080 on your host machine to port 80 inside the container (where Nginx is listening).
* `--rm`: Automatically removes the container when it stops.
* `--name ttrpg-tracker-app`: Assigns a name to the running container.
* `ttrpg-initiative-tracker`: The name of the image you built.
You can then access the application at `http://localhost:8080`.
You can then access the application at `http://localhost:8080`.
**4. Production Deployment Considerations:**
* When deploying to a production environment (e.g., a cloud provider, your own server), you should **not** copy your `.env.local` file into the Docker image.
* Instead, configure the `REACT_APP_FIREBASE_...` environment variables directly in your hosting platform's settings or pass them to the Docker container at runtime (if your application is set up to read them at runtime, though Create React App bakes them in at build time).
* If your CI/CD pipeline builds the Docker image, ensure these environment variables are securely provided to the build environment.
* **Implement strict Firebase Security Rules** appropriate for a production application to protect your data.
* When deploying to a production environment (e.g., a cloud provider, your own server), you should **not** copy your `.env.local` file into the Docker image.
* Instead, configure the `REACT_APP_FIREBASE_...` environment variables directly in your hosting platform's settings or pass them to the Docker container at runtime (if your application is set up to read them at runtime, though Create React App bakes them in at build time).
* If your CI/CD pipeline builds the Docker image, ensure these environment variables are securely provided to the build environment.
* **Implement strict Firebase Security Rules** appropriate for a production application to protect your data.
## Project Structure
ttrpg-initiative-tracker/├── .dockerignore # Specifies intentionally untracked files that Docker should ignore├── .env.example # Example environment variables├── .env.local # Local environment variables (ignored by Git)├── .gitignore # Specifies intentionally untracked files that Git should ignore├── Dockerfile # Instructions to build the Docker image├── package-lock.json # Records exact versions of dependencies├── package.json # Project metadata and dependencies├── postcss.config.js # PostCSS configuration (for Tailwind CSS)├── tailwind.config.js # Tailwind CSS configuration├── public/ # Static assets│ ├── favicon.ico│ ├── index.html # Main HTML template│ └── manifest.json└── src/ # React application source code├── App.js # Main application component├── index.css # Global styles (including Tailwind directives)└── index.js # React entry point
`ttrpg-initiative-tracker/`
- ` .dockerignore` # Specifies intentionally untracked files that Docker should ignore
- ` .env.example` # Example environment variables
- ` .env.local` # Local environment variables (ignored by Git)
- ` .gitignore` # Specifies intentionally untracked files that Git should ignore
- ` Dockerfile` # Instructions to build the Docker image
- ` package-lock.json` # Records exact versions of dependencies
- ` package.json` # Project metadata and dependencies
- ` postcss.config.js` # PostCSS configuration (for Tailwind CSS)
- ` tailwind.config.js` # Tailwind CSS configuration
- ` public/` # Static assets
- ` favicon.ico`
- ` index.html` # Main HTML template
- ` manifest.json`
- ` src/` # React application source code
- ` App.js` # Main application component
- ` index.css` # Global styles (including Tailwind directives)
- ` index.js` # React entry point
## Contributing