adding docs

README.md

@@ -0,0 +1,139 @@
+# Neptune - Cybersecurity Incident Journal
+
+A self-hosted web application for cybersecurity teams to track, document, and visualize security incidents.
+
+## Features
+
+- **Incident Timeline** — chronological log of security events with severity levels, team assignments, and comments
+- **Network Map** — interactive canvas-based network topology diagram (drag/drop nodes, draw connections, add zone shapes)
+- **Document Templates** — structured forms for standardized documentation: Deployments, Attacks, Incident Reports, Remediations, and Exercises
+- **Team-based Organization** — built-in teams: Blue Team, Red Team, SOC, Threat Intel
+- **External Authentication** — login via [Jakach Auth](https://auth.jakach.ch)
+
+## Prerequisites
+
+- [Docker](https://docs.docker.com/engine/install/) and [Docker Compose](https://docs.docker.com/compose/install/)
+- A Jakach Auth account for authentication
+- Port **8081** available on the host (configurable)
+
+## Quick Start
+
+```bash
+git clone https://git.jakach.ch/jakach/armeech-neptune.git
+cd armech-neptune
+docker compose up -d
+```
+
+Open [http://localhost:8081](http://localhost:8081) in your browser.
+
+The first user to log in becomes an **admin**. Subsequent users are assigned the **user** role by default.
+
+## Configuration
+
+### Environment Variables (backend)
+
+Set these on the `php` service in `docker-compose.yml`:
+
+| Variable | Default | Description |
+|---|---|---|
+| `DB_HOST` | `mysql` | MySQL hostname |
+| `DB_NAME` | `neptune` | Database name |
+| `DB_USER` | `neptune` | Database user |
+| `DB_PASS` | `neptune_pass` | Database password |
+
+### MySQL Root Password
+
+The MySQL root password defaults to `neptune_root_pass`. Change it in the `mysql` and `php` environment sections of `docker-compose.yml`.
+
+### Port
+
+The web interface binds to `8081:80` by default. Change the left side of the port mapping in `docker-compose.yml` to use a different port.
+
+## Project Structure
+
+```
+├── backend/
+│   ├── api/index.php        # Single-file REST API (all endpoints)
+│   └── config/database.php  # Database connection & auto-migration
+├── docker/
+│   ├── Dockerfile.php       # PHP 8.2-FPM image build
+│   ├── nginx.conf           # Nginx reverse proxy config
+│   ├── php.ini              # PHP session configuration
+│   └── init.sql             # Database schema and seed data
+├── frontend/
+│   ├── index.html           # Single-page application (SPA)
+│   ├── assets/js/app.js     # Frontend logic (Vanilla JS)
+│   └── assets/css/style.css # Custom dark theme styles
+├── docker-compose.yml       # Container orchestration
+└── .gitea/workflows/        # CI/CD pipeline (Gitea Actions)
+```
+
+## API Endpoints
+
+All API routes are under `/api/`. Authentication is via PHP session (set on login).
+
+| Method | Path | Auth | Description |
+|---|---|---|---|
+| GET | `/api/session` | No | Check login session status |
+| POST | `/api/login` | No | Authenticate via Jakach Auth token |
+| POST | `/api/logout` | No | Destroy session |
+| GET | `/api/registration` | No | Check if new user registration is enabled |
+| POST | `/api/registration` | Admin | Enable/disable new user registration |
+| GET | `/api/settings` | Admin | List all registered users |
+| POST | `/api/settings` | Admin | Add user by Jakach Auth token |
+| DELETE | `/api/settings` | Admin | Remove a user |
+| GET/POST | `/api/teams[/{id}]` | Yes | List / create teams |
+| GET/POST/PUT/DELETE | `/api/events[/{id}]` | Yes | CRUD timeline events |
+| GET/POST | `/api/comments` | Yes | List / create comments on events |
+| GET/POST/PUT/DELETE | `/api/nodes[/{id}]` | Yes | CRUD network map nodes |
+| GET/POST/DELETE | `/api/links[/{id}]` | Yes | CRUD network connections |
+| GET/POST/PUT/DELETE | `/api/shapes[/{id}]` | Yes | CRUD network zone shapes |
+| GET/POST/PUT/DELETE | `/api/documents[/{id}]` | Yes | CRUD structured documents |
+
+## User Roles
+
+- **admin** — Access to Settings modal (add/remove users, toggle registration), full CRUD on all resources
+- **user** — Full CRUD on events, documents, network map. Cannot access Settings.
+
+Registration can be disabled by an admin via **Settings → New User Registration** toggle. When disabled, only existing users can log in; new users see a "Registration is disabled" error.
+
+## Deployment
+
+### Production (Docker Compose)
+
+```bash
+docker compose up -d --build
+```
+
+### CI/CD (Gitea Actions)
+
+The project includes a `.gitea/workflows/deploy.yml` that auto-deploys on push to `main`. Configure these [secrets/variables](https://docs.gitea.com/usage/actions):
+
+| Secret/Variable | Description |
+|---|---|
+| `SSH_KEY` | Private SSH key for deployment server |
+| `SSH_USER` (var) | SSH username |
+| `SSH_IP` (var) | Deployment server IP |
+| `GIT_USER` (var) | Gitea username for repo access |
+| `GIT_TOKEN` (secret) | Gitea personal access token |
+
+## Updating
+
+```bash
+git pull origin main
+docker compose down
+docker compose up -d --build
+```
+
+Database schema migrations run automatically on container startup via `backend/config/database.php`.
+
+## Tech Stack
+
+| Layer | Technology |
+|---|---|
+| Frontend | Vanilla JavaScript, Bootstrap 5.3, Font Awesome 6, HTML5 Canvas |
+| Backend | PHP 8.2 (no framework) |
+| Database | MySQL 8.0 |
+| Web Server | Nginx (reverse proxy to PHP-FPM) |
+| Auth | External — Jakach Auth (OAuth-like token exchange) |
+| Containerization | Docker Compose (nginx, php, mysql) |