refactor: 🎨 rewrite readme
This commit is contained in:
@@ -1,35 +1,209 @@
|
|||||||
# EchoLog
|
<div align="center">
|
||||||
|
<img src="https://projects.jdbnet.co.uk/echolog/img/favicon.png" alt="EchoLog" width="200" />
|
||||||
|
|
||||||
|
# EchoLog
|
||||||
|
</div>
|
||||||
|
|
||||||
EchoLog is a simple, modern homelab journal web app. It lets you document what you did each day, search and filter your entries, and review your homelab journey over time.
|
A Flask-based web application for personal homelab journaling. Track your daily activities, maintain a streak, and search through your journal entries with a modern, PWA-enabled interface.
|
||||||
|
|
||||||
## Features
|
## Features
|
||||||
- Add daily journal entries with multi-line support
|
|
||||||
- Edit and delete entries using a sleek modal interface
|
|
||||||
- Search and filter entries by keyword or date
|
|
||||||
- Pagination for easy browsing of large journals
|
|
||||||
- Optional login for privacy (can be enabled via environment variable)
|
|
||||||
- Beautiful dark mode UI powered by Tailwind CSS
|
|
||||||
- MySQL database backend for reliable storage
|
|
||||||
|
|
||||||
## How it works
|
- **Daily Journal Entries**: Create and manage journal entries for any date
|
||||||
- Entries are saved to a MySQL database, with connection details set via environment variables
|
- **Streak Tracking**: Automatically calculates consecutive days with entries
|
||||||
- The web interface is built with Flask and styled with Tailwind CSS
|
- **Search Functionality**: Search by keyword or filter by specific date
|
||||||
- All features are accessible from a single, responsive page
|
- **PWA Support**: Progressive Web App with offline capabilities and installable on mobile devices
|
||||||
- You can enable login protection and set credentials using environment variables
|
- **Modern UI**: Beautiful gradient design with Tailwind CSS and responsive layout
|
||||||
|
- **Optional Authentication**: Enable login protection with environment variables
|
||||||
|
- **MySQL Backend**: Robust data persistence with MySQL/MariaDB
|
||||||
|
- **Docker Ready**: Easy deployment with Docker and Docker Compose
|
||||||
|
- **Kubernetes Support**: Includes Kubernetes deployment manifest
|
||||||
|
|
||||||
## Docs
|
## Quick Start with Docker
|
||||||
For more information, see the [Docs](https://echolog.jdbnet.co.uk).
|
|
||||||
|
|
||||||
## Environment Variables
|
### Docker Run
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker run -d \
|
||||||
|
--name echolog \
|
||||||
|
-p 5000:5000 \
|
||||||
|
-e MYSQL_HOST=10.10.2.27 \
|
||||||
|
-e MYSQL_USER=echolog \
|
||||||
|
-e MYSQL_PASSWORD=your_password \
|
||||||
|
-e MYSQL_DATABASE=echolog \
|
||||||
|
-e SECRET_KEY=your_secret_key \
|
||||||
|
-e TZ=Europe/London \
|
||||||
|
-e LOGIN_ENABLED=true \
|
||||||
|
-e LOGIN_USERNAME=admin \
|
||||||
|
-e LOGIN_PASSWORD=your_password \
|
||||||
|
docker.jdbnet.co.uk/public/echolog:latest
|
||||||
```
|
```
|
||||||
MYSQL_HOST=10.10.2.27
|
|
||||||
MYSQL_USER=echolog
|
### Docker Compose
|
||||||
MYSQL_PASSWORD=gHH0&nGWK!@8Y5
|
|
||||||
MYSQL_DATABASE=echolog
|
```yaml
|
||||||
SECRET_KEY=bgSNcrA0gZiRX9LbZmminf2LItEXeo
|
version: '3.8'
|
||||||
TZ=Europe/London
|
|
||||||
LOGIN_ENABLED=true
|
services:
|
||||||
LOGIN_USERNAME=jamie
|
echolog:
|
||||||
LOGIN_PASSWORD=jamieB223
|
image: docker.jdbnet.co.uk/public/echolog:latest
|
||||||
```
|
container_name: echolog
|
||||||
|
restart: unless-stopped
|
||||||
|
ports:
|
||||||
|
- "5000:5000"
|
||||||
|
environment:
|
||||||
|
- MYSQL_HOST=10.10.2.27
|
||||||
|
- MYSQL_USER=echolog
|
||||||
|
- MYSQL_PASSWORD=your_password
|
||||||
|
- MYSQL_DATABASE=echolog
|
||||||
|
- SECRET_KEY=your_secret_key
|
||||||
|
- TZ=Europe/London
|
||||||
|
- LOGIN_ENABLED=true
|
||||||
|
- LOGIN_USERNAME=admin
|
||||||
|
- LOGIN_PASSWORD=your_password
|
||||||
|
```
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
### Environment Variables
|
||||||
|
|
||||||
|
- `MYSQL_HOST`: MySQL/MariaDB host (default: localhost)
|
||||||
|
- `MYSQL_USER`: Database user (default: root)
|
||||||
|
- `MYSQL_PASSWORD`: Database password (default: empty)
|
||||||
|
- `MYSQL_DATABASE`: Database name (default: echolog)
|
||||||
|
- `SECRET_KEY`: Flask secret key for sessions (**REQUIRED in production!**)
|
||||||
|
- `TZ`: Timezone for date handling (default: UTC)
|
||||||
|
- `LOGIN_ENABLED`: Enable login protection (default: false)
|
||||||
|
- `LOGIN_USERNAME`: Username for authentication (default: admin)
|
||||||
|
- `LOGIN_PASSWORD`: Password for authentication (default: admin)
|
||||||
|
|
||||||
|
### Database Setup
|
||||||
|
|
||||||
|
The application automatically initializes the database schema on first run. Ensure the database and user exist with appropriate permissions:
|
||||||
|
|
||||||
|
```sql
|
||||||
|
CREATE DATABASE echolog;
|
||||||
|
CREATE USER 'echolog'@'%' IDENTIFIED BY 'your_password';
|
||||||
|
GRANT ALL PRIVILEGES ON echolog.* TO 'echolog'@'%';
|
||||||
|
FLUSH PRIVILEGES;
|
||||||
|
```
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
### Creating Entries
|
||||||
|
|
||||||
|
1. Access the web interface at `http://your-server:5000`
|
||||||
|
2. Enter a journal entry in the text area
|
||||||
|
3. Select the date (defaults to today)
|
||||||
|
4. Click "Add Entry" to save
|
||||||
|
|
||||||
|
### Searching
|
||||||
|
|
||||||
|
- Use the search box to find entries by keyword
|
||||||
|
- Use the date picker to filter by specific date
|
||||||
|
- Combine both for advanced filtering
|
||||||
|
|
||||||
|
### Managing Entries
|
||||||
|
|
||||||
|
- **Edit**: Click the edit icon on any entry to modify it
|
||||||
|
- **Delete**: Click the delete icon to remove an entry permanently
|
||||||
|
- Use pagination controls to navigate through older entries
|
||||||
|
|
||||||
|
### Streak Tracking
|
||||||
|
|
||||||
|
The streak counter automatically tracks consecutive days with journal entries. The streak includes today or yesterday to start, and continues as long as you have entries on consecutive days.
|
||||||
|
|
||||||
|
## Kubernetes Deployment
|
||||||
|
|
||||||
|
The project includes a Kubernetes deployment manifest. See `deployment.yml` for details.
|
||||||
|
|
||||||
|
**Example Kubernetes deployment:**
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
apiVersion: apps/v1
|
||||||
|
kind: Deployment
|
||||||
|
metadata:
|
||||||
|
name: echolog
|
||||||
|
namespace: echolog
|
||||||
|
spec:
|
||||||
|
replicas: 1
|
||||||
|
template:
|
||||||
|
spec:
|
||||||
|
containers:
|
||||||
|
- name: echolog
|
||||||
|
image: docker.jdbnet.co.uk/public/echolog:latest
|
||||||
|
ports:
|
||||||
|
- containerPort: 5000
|
||||||
|
env:
|
||||||
|
- name: SECRET_KEY
|
||||||
|
valueFrom:
|
||||||
|
secretKeyRef:
|
||||||
|
name: echolog-secrets
|
||||||
|
key: secret-key
|
||||||
|
- name: MYSQL_HOST
|
||||||
|
value: "mysql-service"
|
||||||
|
- name: MYSQL_USER
|
||||||
|
value: "echolog"
|
||||||
|
- name: MYSQL_PASSWORD
|
||||||
|
valueFrom:
|
||||||
|
secretKeyRef:
|
||||||
|
name: echolog-secrets
|
||||||
|
key: mysql-password
|
||||||
|
- name: MYSQL_DATABASE
|
||||||
|
value: "echolog"
|
||||||
|
- name: TZ
|
||||||
|
value: "Europe/London"
|
||||||
|
- name: LOGIN_ENABLED
|
||||||
|
value: "true"
|
||||||
|
- name: LOGIN_USERNAME
|
||||||
|
valueFrom:
|
||||||
|
secretKeyRef:
|
||||||
|
name: echolog-secrets
|
||||||
|
key: username
|
||||||
|
- name: LOGIN_PASSWORD
|
||||||
|
valueFrom:
|
||||||
|
secretKeyRef:
|
||||||
|
name: echolog-secrets
|
||||||
|
key: password
|
||||||
|
```
|
||||||
|
|
||||||
|
## Progressive Web App (PWA)
|
||||||
|
|
||||||
|
EchoLog can be installed as a Progressive Web App on supported devices:
|
||||||
|
|
||||||
|
- **Mobile**: Add to home screen from browser menu
|
||||||
|
- **Desktop**: Install from browser address bar
|
||||||
|
- **Offline**: Works offline with cached content
|
||||||
|
|
||||||
|
## Security Notes
|
||||||
|
|
||||||
|
- **ENABLE LOGIN** in production by setting `LOGIN_ENABLED=true`
|
||||||
|
- **CHANGE THE DEFAULT CREDENTIALS** if using authentication
|
||||||
|
- **CHANGE THE SECRET_KEY** in production - use a strong random string (e.g., `openssl rand -hex 32`)
|
||||||
|
- Use strong passwords for database access
|
||||||
|
- Ensure database connections are secured (consider SSL/TLS for MySQL connections)
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### Database Connection Issues
|
||||||
|
|
||||||
|
- Ensure MySQL/MariaDB is running and accessible from the container
|
||||||
|
- Check database credentials in environment variables
|
||||||
|
- Verify database and user exist with proper permissions
|
||||||
|
- Check network connectivity between container and database
|
||||||
|
|
||||||
|
### Application Not Starting
|
||||||
|
|
||||||
|
- Check container logs: `docker logs echolog`
|
||||||
|
- Verify all required environment variables are set
|
||||||
|
- Ensure port 5000 is not already in use
|
||||||
|
- Check that MySQL/MariaDB is reachable
|
||||||
|
|
||||||
|
### Login Not Working
|
||||||
|
|
||||||
|
- Verify `LOGIN_ENABLED` is set to `true`
|
||||||
|
- Check `LOGIN_USERNAME` and `LOGIN_PASSWORD` are set correctly
|
||||||
|
- Ensure `SECRET_KEY` is set for session management
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
This project is provided as-is for personal homelab journaling.
|
||||||
Reference in New Issue
Block a user