Skip to content

Commit

Permalink
Merge pull request #18 from yoanbernabeu/17-set-up-project-documentat…
Browse files Browse the repository at this point in the history
…ion-with-mkdocs

17 set up project documentation with mkdocs
  • Loading branch information
yoanbernabeu authored Dec 26, 2024
2 parents 9ecc151 + 26679d1 commit 2d0ea73
Show file tree
Hide file tree
Showing 8 changed files with 455 additions and 0 deletions.
62 changes: 62 additions & 0 deletions .docs/docs/index.md
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)
127 changes: 127 additions & 0 deletions .docs/docs/installation.md
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
90 changes: 90 additions & 0 deletions .docs/docs/stylesheets/extra.css
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;
}
62 changes: 62 additions & 0 deletions .docs/docs/usage.md
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
Loading

0 comments on commit 2d0ea73

Please sign in to comment.