-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #18 from yoanbernabeu/17-set-up-project-documentat…
…ion-with-mkdocs 17 set up project documentation with mkdocs
- Loading branch information
Showing
8 changed files
with
455 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 <username> <password> | ||
``` | ||
|
||
## 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 <username> <password> | ||
``` | ||
|
||
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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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; | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
Oops, something went wrong.