Merge pull request #830 from dreamteamprod/dev

Simplify docker compose file and update documentation

Author: Tim020

README.md

@@ -1,42 +1,119 @@
 # DigiScript
 
-A digital script project for cueing theatrical shows
+**Real-time digital script management for theatrical productions**
 
-**Main Status:**
 [![ESLint](https://github.com/dreamteamprod/DigiScript/actions/workflows/nodelint.yml/badge.svg?branch=main)](https://github.com/dreamteamprod/DigiScript/actions/workflows/nodelint.yml)
+
 [![Pylint](https://github.com/dreamteamprod/DigiScript/actions/workflows/pylint.yml/badge.svg?branch=main)](https://github.com/dreamteamprod/DigiScript/actions/workflows/pylint.yml)
 
-**Dev Status:**
-[![ESLint](https://github.com/dreamteamprod/DigiScript/actions/workflows/nodelint.yml/badge.svg?branch=dev)](https://github.com/dreamteamprod/DigiScript/actions/workflows/nodelint.yml)
-[![Pylint](https://github.com/dreamteamprod/DigiScript/actions/workflows/pylint.yml/badge.svg?branch=dev)](https://github.com/dreamteamprod/DigiScript/actions/workflows/pylint.yml)
+## Overview
+
+DigiScript is a full-stack web application designed to modernize theatrical show management. Built for stage managers, technical directors, and production teams, it provides real-time script display, intelligent cue management, and collaborative show control in a browser-based interface.
+
+DigiScript eliminates the need for paper scripts and manual cue sheets, while keeping your entire show and team synchronized in real-time.
+
+## Who Should Use DigiScript
+
+**Stage Managers** looking to eliminate paper scripts and manual cue tracking during live performances
+
+**Technical Directors** managing complex shows with multiple cue types and microphone assignments
+
+**Production Teams** needing real-time collaboration across multiple devices during rehearsals and performances
+
+**Theater Companies** running shows over extended periods who need to track session history and maintain multiple script versions
+
+## Key Features
+
+### Real-Time Multi-Client Synchronization
+
+DigiScript's WebSocket-based architecture enables seamless collaboration during live performances. One user acts as the "leader," controlling the script position, while all other connected clients—whether logged in or not—automatically follow along in real-time. If the leader disconnects, the system automatically elects a new leader, ensuring uninterrupted show operations.
+
+![Live show interface with cues](docs/images/live_show/live_show_full_mode_with_cues.png)
+*Live show view with color-coded cues synchronized across all connected clients*
+
+### Intelligent Cue Management
+
+Create custom cue types (lighting, sound, special effects, etc.) with visual color coding for instant recognition. Cues can be attached to dialogue lines, stage directions, or dedicated cue lines. The system tracks cues across script revisions, making it easy to manage different versions of your show.
+
+![Cue configuration interface](docs/images/config_show/cue_configuration_with_cues.png)
+*Cue configuration showing color-coded technical cues attached to script lines*
+
+### Script Revisions
+
+DigiScript's revision system functions like version control for your script. Create new revisions from any previous version, not just the latest, enabling parallel development paths. The visual revision graph shows branching history, making it easy to track changes and roll back if needed. All cues and configurations are tied to specific revisions, preserving the complete history of your production.
+
+![Script revision graph](docs/images/config_show/script_revision_graph_branched.png)
+*Interactive revision graph showing branching script history with visual node representation*
+
+### Advanced Microphone Management
+
+DigiScript's microphone management system provides graphical allocation matrices for assigning microphones to characters across scenes. The system automatically detects conflicts when the same microphone needs to be reassigned between characters, color-coding them based on urgency (orange for tight changeovers within an act, blue for changeovers across act boundaries with interval time). Multiple visualization modes—by microphone, by character, or by cast member help plan mic usage and identify potential issues before they happen.
 
-## Getting started
+![Microphone allocation timeline](docs/images/config_show/mics_timeline.png)
+*Timeline view showing microphone allocations across scenes with conflict detection*
+
+### Flexible Script Modes
+
+Choose between two show modes tailored to your production style:
+
+- **FULL Mode:** Multi-column layout supporting up to 4 simultaneous speakers per line—ideal for ensemble shows, musicals, and scenes with overlapping dialogue
+- **COMPACT Mode:** Single-column streamlined layout—ideal for dialogue-heavy dramas and simpler productions
+
+### Role-Based Access Control (RBAC)
+
+Configure fine-grained permissions for team members. Grant specific users access to edit scripts, manage cues, or start show sessions, while restricting others to view-only access. The permission system operates at the resource level, allowing precise control over who can modify specific show elements.
+
+### Session Tracking & History
+
+Every live show session is recorded with start/end times and can be tagged for organization (e.g., "Dress Rehearsal," "Opening Night"). DigiScript tracks session duration, interval timing, and script position, providing a complete audit trail for your production's run.
+
+## Getting Started
 
 ### Requirements
 
 * Node v24.x (npm 11.x)
 * Python 3.13.x
 
-### Client
+### Quick Start with Docker Compose (Recommended)
 
-This installs and builds the client side files ([nvm](https://github.com/nvm-sh/nvm) recommended)
+The easiest way to run DigiScript is through Docker compose (there is a `docker-compose.yml` file [included](./docker-compose.yaml)).:
+
+```shell
+docker-compose up -d
+```
+
+DigiScript will be available at `http://localhost:8080`
+
+### Manual Installation
+
+#### Client
+
+Build the frontend (output goes to `../server/static/`):
 
 ```shell
 cd client
 npm ci
 npm run build
 ```
 
-### Server
+#### Server
 
-This installs the Python requirements needed to run the server ([pyenv](https://github.com/pyenv/pyenv) recommended)
+Install Python dependencies and run the server:
 
 ```shell
 cd server
 pip install -r requirements.txt
+python3 main.py
 ```
 
-## Other Documentation
+The server will be available at `http://localhost:8080`
+
+### First Launch Setup
+
+On first launch, DigiScript will prompt you to create an administrator user. From there, you can create shows, configure users, and begin building your production.
+
+For detailed setup instructions and usage guides, see the [full documentation](https://github.com/dreamteamprod/DigiScript/tree/main/docs).
+
+## License
 
-* **[Development Guide](./documentation/development.md)**
-* **[Deployment Guide](./documentation/deployment.md)**
+See the [LICENSE](./LICENSE) file for licensing information.

docker-compose.yaml

@@ -7,85 +7,10 @@ services:
       context: .
       dockerfile: Dockerfile
     restart: always
-    container_name: DS-Server
-    environment:
-      DOCKER_DEPLOYMENT: "true"
+    container_name: DigiScript
     ports:
       - 8080:8080
     volumes:
       - dssrv:/server/conf
-
-  prometheus:
-    image: prom/prometheus
-    restart: always
-    volumes:
-      - ./reporting/prometheus:/etc/prometheus/
-      - prometheus_data:/prometheus
-    command:
-      - '--config.file=/etc/prometheus/prometheus.yml'
-      - '--storage.tsdb.path=/prometheus'
-      - '--web.console.libraries=/usr/share/prometheus/console_libraries'
-      - '--web.console.templates=/usr/share/prometheus/consoles'
-    ports:
-      - 9090:9090
-    extra_hosts:
-      - "host.docker.internal:host-gateway"
-    links:
-      - cadvisor:cadvisor
-    depends_on:
-      - cadvisor
-      - node-exporter
-      - server
-
-  node-exporter:
-    image: prom/node-exporter
-    volumes:
-      - /proc:/host/proc:ro
-      - /sys:/host/sys:ro
-      - /:/rootfs:ro
-    command:
-      - '--path.procfs=/host/proc'
-      - '--path.sysfs=/host/sys'
-      - --collector.filesystem.ignored-mount-points
-      - '^/(sys|proc|dev|host|etc|rootfs/var/lib/docker/containers|rootfs/var/lib/docker/overlay2|rootfs/run/docker/netns|rootfs/var/lib/docker/aufs)($$|/)'
-      - '--collector.systemd'
-      - '--collector.processes'
-    ports:
-      - 9100:9100
-    restart: always
-    deploy:
-      mode: global
-
-  cadvisor:
-    image: gcr.io/cadvisor/cadvisor:latest
-    volumes:
-      - /:/rootfs:ro
-      - /var/run:/var/run:rw
-      - /sys:/sys:ro
-      - /var/lib/docker/:/var/lib/docker:ro
-    ports:
-      - 8090:8080
-    restart: always
-    deploy:
-      mode: global
-
-  grafana:
-    image: grafana/grafana
-    user: '472'
-    restart: always
-    environment:
-      GF_INSTALL_PLUGINS: 'grafana-clock-panel,grafana-simple-json-datasource'
-    volumes:
-      - grafana_data:/var/lib/grafana
-      - ./reporting/grafana/provisioning:/etc/grafana/provisioning/
-    env_file:
-      - ./reporting/grafana/config.env
-    ports:
-      - 3000:3000
-    depends_on:
-      - prometheus
-
 volumes:
   dssrv:
-  prometheus_data:
-  grafana_data:

documentation/deployment.md

@@ -9,7 +9,7 @@ cd server
 ./main.py
 ```
 
-## Running using docker
+## Running using Docker
 
 This will start DigiScript running, and map port 8080 locally to 8080 on the container
 

documentation/development.md

@@ -1,5 +1,45 @@
 # Development Guide
 
+**Main Status:**
+
+[![ESLint](https://github.com/dreamteamprod/DigiScript/actions/workflows/nodelint.yml/badge.svg?branch=main)](https://github.com/dreamteamprod/DigiScript/actions/workflows/nodelint.yml)
+
+[![Pylint](https://github.com/dreamteamprod/DigiScript/actions/workflows/pylint.yml/badge.svg?branch=main)](https://github.com/dreamteamprod/DigiScript/actions/workflows/pylint.yml)
+
+**Dev Status:**
+
+[![ESLint](https://github.com/dreamteamprod/DigiScript/actions/workflows/nodelint.yml/badge.svg?branch=dev)](https://github.com/dreamteamprod/DigiScript/actions/workflows/nodelint.yml)
+
+[![Pylint](https://github.com/dreamteamprod/DigiScript/actions/workflows/pylint.yml/badge.svg?branch=dev)](https://github.com/dreamteamprod/DigiScript/actions/workflows/pylint.yml)
+
+## Architecture Highlights
+
+DigiScript uses split front-end and back-end architecture with the following key technologies:
+
+- **Real-time WebSocket protocol** with leader-follower architecture for synchronized multi-client operation
+- **SQLAlchemy 2.0 ORM** with sophisticated revision-scoped associations for managing complex script relationships
+- **Vuex state management** with modular structure and localStorage persistence for reactive UIs
+- **JWT authentication** with role-based access control using bitmask permissions
+- **Compiled script caching** with gzip compression for fast live show performance
+- **Automatic database migrations** via Alembic, checked on server startup
+
+## Contributing
+
+Contributions are welcome! Please ensure all client and server code passes linting checks before submitting pull requests:
+
+```shell
+# Client linting
+cd client
+npm run lint
+
+# Server linting
+cd server
+ruff check server/
+ruff format server/
+```
+
+When creating pull requests for new features, target the `dev` branch.
+
 ## Websocket messaging
 
 Websockets are used to communicate between the clients and the server.