diff --git a/.docs/docs/index.md b/.docs/docs/index.md new file mode 100644 index 0000000..594cf86 --- /dev/null +++ b/.docs/docs/index.md @@ -0,0 +1,62 @@ +# OpenStreamPoll Documentation + +## Welcome to OpenStreamPoll + +OpenStreamPoll is an open-source live polling platform specifically designed for streamers. It enables real-time audience engagement through interactive polls, featuring instant results and seamless integration with popular streaming tools. + +## Quick Start + +=== "Quick Install" + ```bash + git clone https://github.com/yoanbernabeu/OpenStreamPoll.git + cd OpenStreamPoll + make deploy + ``` + +=== "Docker" + ```bash + docker run -d -p 80:80 \ + -e SERVER_NAME=:80 \ + -e APP_ENV=prod \ + --name openstreampoll \ + yoanbernabeu/openstreampoll:latest + ``` + +=== "Development" + ```bash + git clone https://github.com/yoanbernabeu/OpenStreamPoll.git + cd OpenStreamPoll + make first-install + ``` + +## Key Features + +- **Live Polling System** + - Create instant polls + - Real-time results + - Multiple choice questions + +- **Stream Integration** + - Native OBS integration + - Customizable overlays + - QR code display + +- **Easy Administration** + - User-friendly interface + - Poll management + - Results tracking + +## Project Overview + +OpenStreamPoll is built with: + +- PHP 8.3 with Symfony 7.2 +- Alpine.js & HTMX +- Tailwind CSS with DaisyUI +- Docker & FrankenPHP + +For detailed information, check out: + +- [Installation Guide](installation.md) +- [Usage Guide](usage.md) +- [GitHub Repository](https://github.com/yoanbernabeu/OpenStreamPoll) diff --git a/.docs/docs/installation.md b/.docs/docs/installation.md new file mode 100644 index 0000000..0dc6410 --- /dev/null +++ b/.docs/docs/installation.md @@ -0,0 +1,127 @@ +# Installation + +This page details the different methods for installing OpenStreamPoll. + +## Prerequisites + +Before starting the installation, make sure you have: + +- PHP 8.3 or higher +- Composer +- Symfony CLI +- SQLite +- Make +- Docker (recommended) + +## 1. Production Deployment with Make (Recommended) + +### Quick Steps + +```bash +# Clone the repository +git clone https://github.com/yoanbernabeu/OpenStreamPoll.git +cd OpenStreamPoll + +# Launch deployment +make deploy +``` + +### Process Details + +The `make deploy` command will automatically: + +1. Create a `compose.prod.yaml` file from the template +2. Ask for your domain name +3. Start Docker containers +4. Create and configure the database +5. Create the administrator account + +## 2. Manual Production Deployment + +If you prefer to control each step: + +```bash +# Clone the repository +git clone https://github.com/yoanbernabeu/OpenStreamPoll.git +cd OpenStreamPoll + +# Create production configuration +cp compose.yaml compose.prod.yaml + +# Configure domain in compose.prod.yaml +# SERVER_NAME=yourdomain.com (use :80 without SSL) + +# Start services +docker compose -f compose.prod.yaml up -d + +# Create database +docker compose -f compose.prod.yaml exec openstreampoll php bin/console doctrine:database:create + +# Run migrations +docker compose -f compose.prod.yaml exec openstreampoll php bin/console doctrine:migrations:migrate --no-interaction + +# Create admin user +docker compose -f compose.prod.yaml exec openstreampoll php bin/console app:create-user +``` + +## 3. Development Installation + +For local development with hot-reload: + +```bash +# Initial installation +make first-install + +# Normal startup +make start + +# Useful commands +make stop # Stop server +make reset-db # Reset database +make tests # Run tests +make before-commit # Pre-commit checks +``` + +## 4. Quick Local Testing with Docker + +For rapid testing: + +```bash +# Start container +docker run -d -p 80:80 \ + -e SERVER_NAME=:80 \ + -e APP_ENV=prod \ + --name openstreampoll \ + yoanbernabeu/openstreampoll:latest + +# Database setup +docker exec openstreampoll php bin/console doctrine:database:create +docker exec openstreampoll php bin/console doctrine:migrations:migrate --no-interaction +docker exec openstreampoll php bin/console app:create-user +``` + +The application will be accessible at `http://localhost` + +## Troubleshooting + +### Common Errors + +1. **Permission Issues** + - Check write permissions on the `var/` directory + - Use `chmod -R 777 var/` if needed + +2. **Database Errors** + - Verify SQLite is installed + - Ensure database directory is writable + +3. **Docker Container Issues** + - Check logs with `docker compose logs` + - Ensure ports are not already in use + +### Support + +If you encounter problems: + +1. Check [GitHub issues](https://github.com/yoanbernabeu/OpenStreamPoll/issues) +2. Create a new issue if needed +3. For security concerns, contact the maintainer directly diff --git a/.docs/docs/stylesheets/extra.css b/.docs/docs/stylesheets/extra.css new file mode 100644 index 0000000..0cfe22d --- /dev/null +++ b/.docs/docs/stylesheets/extra.css @@ -0,0 +1,90 @@ +:root { + --md-primary-fg-color: #661AE6; + --md-primary-fg-color--light: #8B5CF6; + --md-primary-fg-color--dark: #4C1D95; + --md-accent-fg-color: #8B5CF6; +} + +[data-md-color-scheme="slate"] { + --md-hue: 232; + --md-default-bg-color: #1f2937; + --md-default-fg-color: #f8fafc; + --md-default-fg-color--light: #e2e8f0; + --md-code-bg-color: #111827; + --md-code-fg-color: #e2e8f0; + --md-typeset-a-color: #8B5CF6; +} + +.md-header { + background-color: #111827; +} + +.md-nav__link:hover { + color: #8B5CF6 !important; +} + +.md-typeset code { + background-color: #1f2937; + border: 1px solid #374151; + border-radius: 0.2rem; +} + +.md-typeset pre > code { + background-color: #111827; +} + +.md-nav__item .md-nav__link--active { + color: #8B5CF6; +} + +.md-typeset .admonition { + border-left: 0.2rem solid #8B5CF6; + background-color: #111827; +} + +/* Styles pour les onglets */ +.md-tabs { + background-color: #111827; +} + +.tabbed-set { + border-radius: 0.5rem; + overflow: hidden; + margin: 1.5em 0; +} + +.tabbed-set .tabbed-content { + padding: 1rem; + background-color: #1f2937; + border: 1px solid #374151; + border-top: none; +} + +.tabbed-set .tabbed-labels { + background-color: #111827; + border-bottom: 1px solid #374151; +} + +.tabbed-set .tabbed-labels > label { + color: #e2e8f0; + padding: 0.5rem 1rem; + font-weight: 600; +} + +.tabbed-set .tabbed-labels > label:hover { + color: #8B5CF6; +} + +.tabbed-set .tabbed-labels > input:checked + label { + color: #8B5CF6; + border-bottom: 2px solid #8B5CF6; +} + +/* Active tab content */ +.tabbed-block { + display: none; +} + +.tabbed-block.active { + display: block; +} diff --git a/.docs/docs/usage.md b/.docs/docs/usage.md new file mode 100644 index 0000000..9af7510 --- /dev/null +++ b/.docs/docs/usage.md @@ -0,0 +1,62 @@ +# Usage Guide + +## Creating Polls + +=== "Basic Creation" + 1. Log in to the admin panel + 2. Click "New Poll" + 3. Enter your question + 4. Add answer options + 5. Click "Create" + +=== "Advanced Options" + - Set poll duration + - Configure voting limits + - Enable/disable features + - Save as draft + +=== "Management" + - Edit existing polls + - View results + - Close/reopen polls + - Delete polls + +## OBS Integration + +=== "Poll Display" + 1. Add Browser Source in OBS + 2. Enter URL: `https://yourdomain.com/obs` + 3. Set dimensions (1920x1080 recommended) + 4. Position as needed + +=== "QR Code" + 1. Add Browser Source + 2. URL: `https://yourdomain.com/obs/qr` + 3. Position in corner of stream + 4. Viewers scan to participate + +=== "Admin Panel" + 1. Open OBS Docks menu + 2. Add Custom Browser Dock + 3. URL: `https://yourdomain.com/admin` + 4. Manage polls directly from OBS + +## Best Practices + +=== "Poll Creation" + - Keep questions clear + - Limit options (max 5) + - Use appropriate timing + - Test before going live + +=== "Stream Integration" + - Position polls strategically + - Use consistent styling + - Test visibility on all layouts + - Consider mobile viewers + +=== "Engagement" + - Announce polls clearly + - Give adequate voting time + - Discuss results live + - Thank participants diff --git a/.docs/mkdocs.yml b/.docs/mkdocs.yml new file mode 100644 index 0000000..b8b0364 --- /dev/null +++ b/.docs/mkdocs.yml @@ -0,0 +1,65 @@ +site_name: OpenStreamPoll Documentation +theme: + name: material + language: en + palette: + scheme: slate + primary: deep purple + accent: purple + features: + - navigation.tracking + - navigation.sections + - navigation.expand + - navigation.top + - navigation.footer + - toc.integrate + - content.code.copy + - navigation.instant + - navigation.tabs + - navigation.tabs.sticky + + + font: + text: Roboto + code: Roboto Mono + icon: + repo: fontawesome/brands/github + +extra_css: + - stylesheets/extra.css + +nav: + - Home: index.md + - Installation: installation.md + - Usage: usage.md + +markdown_extensions: + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences + - admonition + - pymdownx.details + - def_list + - tables + - attr_list + - md_in_html + - pymdownx.tabbed: + alternate_style: true + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.details + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + +extra: + social: + - icon: fontawesome/brands/github + link: https://github.com/yoanbernabeu/OpenStreamPoll diff --git a/.github/workflows/mkdocs.yml b/.github/workflows/mkdocs.yml new file mode 100644 index 0000000..49a328e --- /dev/null +++ b/.github/workflows/mkdocs.yml @@ -0,0 +1,28 @@ +name: ci +on: + push: + branches: + - main +permissions: + contents: write +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Configure Git Credentials + run: | + git config user.name github-actions[bot] + git config user.email 41898282+github-actions[bot]@users.noreply.github.com + - uses: actions/setup-python@v5 + with: + python-version: 3.x + - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV + - uses: actions/cache@v4 + with: + key: mkdocs-material-${{ env.cache_id }} + path: .cache + restore-keys: | + mkdocs-material- + - run: pip install mkdocs-material + - run: cd .docs && mkdocs gh-deploy --force \ No newline at end of file diff --git a/Makefile b/Makefile index 67e8864..9dc2435 100644 --- a/Makefile +++ b/Makefile @@ -34,6 +34,11 @@ PHPQA_RUN = $(DOCKER_RUN) --init --rm -v $(PWD):/project -w /project $(PHPQA) #---PHPUNIT-# PHPUNIT = APP_ENV=test $(SYMFONY) php bin/phpunit #------------# + +#---MKDOCS--# +MKDOCS = squidfunk/mkdocs-material +MKDOCS_RUN = $(DOCKER_RUN) --rm -it -p 8000:8000 -v $(PWD)/.docs:/docs $(MKDOCS) +#------------# #---------------------------------------------# s ## === 🆘 HELP ================================================== @@ -170,6 +175,16 @@ qa-lint-schema: ## Lint Doctrine schema. .PHONY: qa-lint-schema #---------------------------------------------# +## === 📚 DOCUMENTATION ========================================= +docs-serve: ## Serve documentation locally + $(MKDOCS_RUN) serve -a 0.0.0.0:8000 +.PHONY: docs-serve + +docs-build: ## Build documentation + $(MKDOCS_RUN) build +.PHONY: docs-build +#---------------------------------------------# + ## === 🔎 TESTS ================================================= tests: ## Run tests. $(MAKE) sf-dd-test diff --git a/templates/home/index.html.twig b/templates/home/index.html.twig index 39f6d23..9319690 100644 --- a/templates/home/index.html.twig +++ b/templates/home/index.html.twig @@ -360,6 +360,12 @@

It's free, open source, and takes just minutes to set up your own instance.

Get Started on GitHub + + + + + Documentation +