Commit All
This commit is contained in:
313
README.md
Normal file
313
README.md
Normal file
@@ -0,0 +1,313 @@
|
||||
# 📅 Turmli Bar Calendar Tool
|
||||
|
||||
A modern, mobile-friendly web application that fetches and displays calendar events from an ICS (iCalendar) feed. Built with Python, FastAPI, and a responsive web interface.
|
||||
|
||||
## ✨ Features
|
||||
|
||||
- **Automatic Daily Updates**: Fetches calendar data automatically every day and every 4 hours
|
||||
- **Mobile-Responsive Design**: Warm, inviting interface optimized for all devices
|
||||
- **Bar-Themed Colors**: Cozy atmosphere with rich browns and warm earth tones
|
||||
- **Custom Branding**: Integrated Turmli Bar logo
|
||||
- **Event Grouping**: Events organized by date for easy viewing
|
||||
- **Caching**: Local caching ensures calendar is available even if the source is temporarily unavailable
|
||||
- **API Endpoints**: JSON API for programmatic access to calendar data
|
||||
- **Real-time Updates**:
|
||||
- Manual refresh button triggers actual ICS file fetch
|
||||
- Auto-refresh with countdown timer (5 minutes)
|
||||
- Status messages showing fetch progress and results
|
||||
- **Container Support**: Docker and Podman compatible for easy deployment
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### Option 1: Container Deployment (Docker/Podman)
|
||||
|
||||
#### Using Docker
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone <repository-url>
|
||||
cd turmli-bar-calendar-tool
|
||||
|
||||
# Deploy with Docker
|
||||
./deploy.sh start
|
||||
|
||||
# Or deploy with Podman (rootless containers)
|
||||
./deploy-podman.sh start
|
||||
```
|
||||
|
||||
The application will be available at `http://localhost:8000`
|
||||
|
||||
### Option 2: Local Development
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Python 3.13 or higher
|
||||
- [uv](https://github.com/astral-sh/uv) package manager (for local development only)
|
||||
|
||||
### Installation
|
||||
|
||||
1. Clone the repository:
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd turmli-bar-calendar-tool
|
||||
```
|
||||
|
||||
2. Install dependencies using uv:
|
||||
```bash
|
||||
uv sync
|
||||
```
|
||||
|
||||
3. Run the server:
|
||||
```bash
|
||||
./run.sh
|
||||
```
|
||||
|
||||
Or directly with uv:
|
||||
```bash
|
||||
uv run uvicorn main:app --host 0.0.0.0 --port 8000 --reload
|
||||
```
|
||||
|
||||
4. Open your browser and navigate to:
|
||||
```
|
||||
http://localhost:8000
|
||||
```
|
||||
|
||||
## 📱 Features & Interface
|
||||
|
||||
### Web Interface
|
||||
- **Responsive Design**: Optimized for mobile phones, tablets, and desktops
|
||||
- **Visual Calendar**: Warm, inviting display with time, location, and all-day indicators
|
||||
- **Bar Atmosphere**: Rich brown and tan colors that evoke a cozy bar environment
|
||||
- **Branded Experience**: Features the Turmli Bar logo with subtle sepia toning
|
||||
- **Smart Refresh**:
|
||||
- Manual refresh button that fetches new data from the ICS source
|
||||
- Auto-refresh countdown timer (5 minutes)
|
||||
- Visual feedback showing fetch progress and results
|
||||
- Displays whether data has changed since last update
|
||||
|
||||
### Event Display
|
||||
- Events grouped by date
|
||||
- Shows next 30 days of events
|
||||
- Clear time indicators for scheduled events
|
||||
- "All Day" badges for full-day events
|
||||
- Location information with map pin icons
|
||||
- Smooth animations and hover effects
|
||||
|
||||
## 🔧 Configuration
|
||||
|
||||
### Timezone
|
||||
By default, the application uses `Europe/Berlin` timezone. To change it, modify the timezone in `main.py`:
|
||||
|
||||
```python
|
||||
tz = pytz.timezone('Europe/Berlin') # Change to your timezone
|
||||
```
|
||||
|
||||
### Calendar URL
|
||||
The calendar ICS URL is configured in `main.py`. To use a different calendar:
|
||||
|
||||
```python
|
||||
CALENDAR_URL = "your-calendar-ics-url-here"
|
||||
```
|
||||
|
||||
### Update Schedule
|
||||
The calendar updates:
|
||||
- Daily at 2:00 AM
|
||||
- Every 4 hours throughout the day
|
||||
|
||||
You can modify the schedule in the `startup_event` function in `main.py`.
|
||||
|
||||
## 🌐 API Endpoints
|
||||
|
||||
### `GET /`
|
||||
Returns the HTML interface with calendar events
|
||||
|
||||
### `GET /api/events`
|
||||
Returns calendar events in JSON format:
|
||||
```json
|
||||
{
|
||||
"events": [
|
||||
{
|
||||
"title": "Meeting",
|
||||
"location": "Conference Room",
|
||||
"start": "2024-01-15T10:00:00",
|
||||
"end": "2024-01-15T11:00:00",
|
||||
"all_day": false
|
||||
}
|
||||
],
|
||||
"last_updated": "2024-01-15T08:00:00"
|
||||
}
|
||||
```
|
||||
|
||||
### `POST /api/refresh`
|
||||
Manually triggers a calendar refresh from the ICS source:
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"message": "Calendar refreshed successfully",
|
||||
"events_count": 15,
|
||||
"previous_count": 14,
|
||||
"data_changed": true,
|
||||
"last_updated": "2024-01-15T08:00:00"
|
||||
}
|
||||
```
|
||||
|
||||
The refresh button in the UI:
|
||||
- Shows a loading spinner while fetching
|
||||
- Displays success/error status
|
||||
- Shows if data has changed
|
||||
- Automatically reloads the page after successful fetch
|
||||
- Resets the auto-refresh countdown timer
|
||||
|
||||
## 🎨 Customization
|
||||
|
||||
### Logo
|
||||
The application displays the Turmli Bar logo (`Vektor-Logo.svg`) in the header. To use a different logo:
|
||||
1. Place your logo file in the project root or `static/` directory
|
||||
2. Update the logo path in `main.py` if needed
|
||||
|
||||
### Styling
|
||||
The interface uses warm, bar-appropriate colors with rich browns (#2c1810, #8b4513), warm tans (#f4e4d4, #d4a574), and cream accents. The design creates a cozy, inviting atmosphere while maintaining excellent readability. Colors are easy on the eyes with subtle gradients and soft shadows. You can customize the appearance by modifying the CSS in the `HTML_TEMPLATE` variable in `main.py`.
|
||||
|
||||
### Event Display Period
|
||||
By default, shows events for the next 30 days. Change this in the `fetch_calendar` function:
|
||||
```python
|
||||
cutoff = now + timedelta(days=30) # Modify the number of days
|
||||
```
|
||||
|
||||
## 🚢 Deployment
|
||||
|
||||
### 🐳 Container Deployment (Docker/Podman)
|
||||
|
||||
#### Quick Start
|
||||
|
||||
```bash
|
||||
# Deploy the application
|
||||
./deploy.sh start # Start on default port 8000
|
||||
PORT=8080 ./deploy.sh start # Start on custom port
|
||||
|
||||
# Manage the application
|
||||
./deploy.sh status # Check container status
|
||||
./deploy.sh logs # View application logs
|
||||
./deploy.sh stop # Stop container
|
||||
./deploy.sh restart # Restart container
|
||||
./deploy.sh update # Pull updates and restart
|
||||
```
|
||||
|
||||
#### Container Files Included
|
||||
|
||||
- **Dockerfile/Containerfile**: Python 3.13 container (uses pip for simplicity)
|
||||
- **docker-compose.yml**: Docker Compose configuration
|
||||
- **podman-compose.yml**: Podman Compose configuration
|
||||
- **deploy.sh**: Docker deployment script
|
||||
- **deploy-podman.sh**: Podman deployment script (supports rootless)
|
||||
|
||||
**Note**: The container uses `pip` for dependency installation to keep things simple. Local development still uses `uv` for better package management.
|
||||
|
||||
##### Podman Support
|
||||
|
||||
Podman is a daemonless, rootless container engine that's a drop-in replacement for Docker:
|
||||
|
||||
```bash
|
||||
# Using Podman deployment script
|
||||
./deploy-podman.sh start
|
||||
|
||||
# Generate systemd service (Podman only)
|
||||
./deploy-podman.sh systemd
|
||||
```
|
||||
|
||||
See [PODMAN_README.md](PODMAN_README.md) for detailed Podman instructions.
|
||||
|
||||
#### Container Features
|
||||
|
||||
- **Simple Build**: Straightforward Python container
|
||||
- **Health Checks**: Built-in monitoring endpoint
|
||||
- **Volume Persistence**: Calendar cache persists between restarts
|
||||
- **Auto-restart**: Container restarts automatically on failure
|
||||
|
||||
#### Environment Variables
|
||||
|
||||
Set the port if needed (default is 8000):
|
||||
```bash
|
||||
PORT=8080 ./deploy.sh start
|
||||
```
|
||||
|
||||
Or use compose directly:
|
||||
```bash
|
||||
# Docker Compose
|
||||
PORT=8080 docker-compose up -d
|
||||
|
||||
# Podman Compose
|
||||
PORT=8080 podman-compose -f podman-compose.yml up -d
|
||||
```
|
||||
|
||||
#### Simple Container Commands
|
||||
|
||||
```bash
|
||||
# Using the deployment script (recommended)
|
||||
./deploy.sh start # Build and start
|
||||
./deploy.sh stop # Stop container
|
||||
./deploy.sh logs # View logs
|
||||
./deploy.sh status # Check health (Docker)
|
||||
./deploy-podman.sh status # Check health (Podman)
|
||||
|
||||
# Or use container commands directly
|
||||
# Docker:
|
||||
docker build -t turmli-calendar .
|
||||
docker run -d -p 8000:8000 -v $(pwd)/calendar_cache.json:/app/calendar_cache.json turmli-calendar
|
||||
|
||||
# Podman (rootless):
|
||||
podman build -t turmli-calendar .
|
||||
podman run -d -p 8000:8000 -v $(pwd)/calendar_cache.json:/app/calendar_cache.json:Z turmli-calendar
|
||||
```
|
||||
|
||||
### Traditional Deployment
|
||||
|
||||
For non-container deployments, use systemd:
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Turmli Bar Calendar Tool
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=youruser
|
||||
WorkingDirectory=/path/to/turmli-bar-calendar-tool
|
||||
ExecStart=/usr/bin/uv run uvicorn main:app --host 0.0.0.0 --port 8000
|
||||
Restart=on-failure
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
### Notes for Internal Use
|
||||
|
||||
- The application runs on a single port (default 8000)
|
||||
- No SSL/HTTPS needed for internal network
|
||||
- Simple Python server is sufficient for ~30 users
|
||||
- Calendar cache persists in `calendar_cache.json`
|
||||
- Automatic refresh every 5 minutes
|
||||
|
||||
## 📝 License
|
||||
|
||||
MIT License - feel free to use and modify as needed.
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
Contributions are welcome! Please feel free to submit a Pull Request.
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
### Calendar not updating
|
||||
- Check the console logs for any error messages
|
||||
- Verify the ICS URL is accessible
|
||||
- Check the `calendar_cache.json` file for cached data
|
||||
|
||||
### Events not showing
|
||||
- Ensure the calendar has events in the next 30 days
|
||||
- Check timezone settings match your location
|
||||
- Verify the ICS file format is valid
|
||||
|
||||
### Port already in use
|
||||
- Change the port in `run.sh` or when running uvicorn directly
|
||||
- Check for other processes using port 8000: `lsof -i :8000`
|
||||
Reference in New Issue
Block a user