Added README.md and License
This commit is contained in:
@@ -1,2 +1,164 @@
|
||||
# ca-lose
|
||||
# CA-Lose
|
||||
|
||||
CA-Lose is a small full-stack app for collecting ticket-sale/order form entries.
|
||||
|
||||
## Tech stack
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Architecture
|
||||
|
||||
- **Frontend**: React + TypeScript + Vite (UI uses MUI + Tailwind, i18n via i18next)
|
||||
- **Backend**: Node.js + Express (also renders a minimal EJS page at `/`)
|
||||
- **Database**: MySQL 8
|
||||
|
||||
In production, the frontend is served by **Nginx** and proxies `/backend/*` to the backend container.
|
||||
|
||||
## Repos & folders
|
||||
|
||||
```
|
||||
backend/ # Express API + EJS views
|
||||
frontend/ # React app (Vite) + Nginx container
|
||||
docker-compose.yml
|
||||
docker-compose.prod.yml
|
||||
```
|
||||
|
||||
## API overview
|
||||
|
||||
The backend router is mounted at `/default`:
|
||||
|
||||
- `GET /default/users` → returns `{ users: string[] }`
|
||||
- `GET /default/confirm-user?username=<name>` → validates user and returns metadata (e.g. next id)
|
||||
- `POST /default/new-entry?username=<name>` → stores a new entry in MySQL
|
||||
|
||||
## Configuration
|
||||
|
||||
### Backend environment variables
|
||||
|
||||
The backend reads configuration from environment variables (and can also load a `backend/.env` file via `dotenv`).
|
||||
|
||||
- `PORT` (e.g. `8004`)
|
||||
- `DB_HOST` (e.g. `ca-lose-mysql` when using Docker Compose)
|
||||
- `DB_USER` (e.g. `root`)
|
||||
- `DB_PASSWORD`
|
||||
- `DB_NAME` (e.g. `ca_lose`)
|
||||
|
||||
### Docker Compose environment
|
||||
|
||||
Both compose files expect `DB_PASSWORD` to be present in your shell environment or a root `.env` file.
|
||||
|
||||
Create a root `.env` (not committed) like:
|
||||
|
||||
```env
|
||||
DB_PASSWORD=change-me
|
||||
```
|
||||
|
||||
## Local development
|
||||
|
||||
### Option A: Docker Compose (backend + database)
|
||||
|
||||
This is the quickest way to get the API + MySQL running.
|
||||
|
||||
```bash
|
||||
docker compose up --build
|
||||
```
|
||||
|
||||
What you get:
|
||||
|
||||
- Backend: http://localhost:8004
|
||||
- MySQL: localhost:3311 (container port 3306)
|
||||
|
||||
Note: In `docker-compose.yml` the `frontend` service is currently commented out.
|
||||
|
||||
### Option B: Run frontend locally (Vite) + run backend & DB
|
||||
|
||||
1. Start DB + backend (Docker):
|
||||
|
||||
```bash
|
||||
docker compose up --build database backend
|
||||
```
|
||||
|
||||
2. Start frontend (local Node):
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm ci
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Open the Vite dev server URL (usually http://localhost:5173).
|
||||
|
||||
Important:
|
||||
|
||||
- During local development (Vite), the frontend currently calls the backend via a hard-coded URL (`http://localhost:8004`).
|
||||
- When the frontend is served by the Nginx container, requests are expected to go through the Nginx proxy at `/backend/*` (see `frontend/nginx.conf`). In that setup the frontend should use `/backend/default/...` instead of `http://localhost:8004/...`.
|
||||
|
||||
## Database setup
|
||||
|
||||
The schema file is in `backend/scheme.sql`.
|
||||
|
||||
- The `users` table is required for the user dropdown.
|
||||
- The backend creates an entry table dynamically per user and date when calling `GET /default/confirm-user`.
|
||||
|
||||
Example (inside MySQL):
|
||||
|
||||
```sql
|
||||
INSERT INTO users (username, first_name, last_name)
|
||||
VALUES ('demo', 'Demo', 'User');
|
||||
```
|
||||
|
||||
## Production / Deployment
|
||||
|
||||
The production compose file builds and runs:
|
||||
|
||||
- `frontend` (Nginx)
|
||||
- `backend` (Express)
|
||||
- `database` (MySQL)
|
||||
- optional infrastructure: `dnsmasq` and `wireguard` (wg-easy)
|
||||
|
||||
Start it:
|
||||
|
||||
```bash
|
||||
docker compose -f docker-compose.prod.yml up -d --build
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- `docker-compose.prod.yml` uses an **external** network called `proxynet`. Create it if it does not exist:
|
||||
|
||||
```bash
|
||||
docker network create proxynet
|
||||
```
|
||||
|
||||
- The production file assigns static IPs; adjust the subnets/IPs if they conflict with your environment.
|
||||
|
||||
## Lint / build
|
||||
|
||||
Frontend:
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm run lint
|
||||
npm run build
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- **Backend does not start / ESM imports**: The backend code uses ESM `import` syntax. Node must treat the backend as an ESM project (commonly by adding `"type": "module"` to `backend/package.json`). Without that, the backend will fail to start (including in Docker).
|
||||
- **MySQL timezone mount**: The compose files mount `./mysql-timezone.cnf` to `/etc/mysql/conf.d/timezone.cnf`. Ensure `mysql-timezone.cnf` is a file (not a directory) with valid MySQL config, or remove/adjust the mount.
|
||||
|
||||
## License
|
||||
|
||||
Licensed under the Apache License 2.0. See [LICENSE](LICENSE).
|
||||
|
||||
Reference in New Issue
Block a user