2 |
3 | # SideQuests - Objective Tracker
4 |
5 | 
6 | 
7 | 
8 |
9 | SideQuests provides an intuitive and mobile friendly web-interface for managing tasks and objectives.
10 |
11 | ## 🐳 Setup
12 |
13 | ### Docker Run
14 |
15 | ```bash
16 | docker run -d \
17 | -p 8080:8080 \
18 | -e PORT=8080 \
19 | -e ADMIN_USERNAME=your_admin_username \
20 | -e ADMIN_PASSWORD=your_admin_password \
21 | -e SECRET_KEY=your_secret_key \
22 | need4swede/sidequests:latest
23 | ```
24 |
25 | ### Docker Compose
26 |
27 | ```yaml
28 | services:
29 | SideQuests:
30 | image: need4swede/sidequests:latest
31 | container_name: SideQuests
32 | ports:
33 | - "8080:8080"
34 | volumes:
35 | - ./instance:/app/instance
36 | environment:
37 | - PORT=8080
38 | - ADMIN_USERNAME=your_admin_username
39 | - ADMIN_PASSWORD=your_admin_password
40 | - SECRET_KEY=your_secret_key
41 |
42 | ```
43 |
44 | ## ✨ Core Functionality
45 |
46 | **Quests**
47 | - Quests contain individual Objectives. Leaving the title blank automatically assigns today's date as the title.
48 |
49 | **Objectives**
50 | - Objectives are individual tasks within Quests. You need to complete every Objectives to finish a Quest.
51 |
52 | ## 🎨 UI Goodies
53 |
54 | **Simple and Straightforward**
55 | - Nothing fancy here! Just enough to keep you on track and focused!
56 |
57 | **Designed for Mobile**
58 | - Fully responsive pages and elements makes for a great PWA experience.
59 |
60 | **Block Level Design**
61 | - Drag and drop elements to easily organize your Quests & Objectives.
62 |
63 | **Dark Mode**
64 | - No brainer.
65 |
66 | ## 🛠️ Technical Stack
67 |
68 | - 🐍 **Backend**: Flask (Python)
69 | - 💾 **Database**: SQLAlchemy with SQLite
70 | - 🌐 **Frontend**: HTML, CSS, JavaScript
--------------------------------------------------------------------------------
/app.py:
--------------------------------------------------------------------------------
1 | # ============================
2 | # 1. Standard Library Imports
3 | # ============================
4 |
5 | import os # Interact with the operating system and handle environment variables
6 | from functools import wraps # Create decorator functions
7 | from datetime import datetime # Work with dates and times
8 | from urllib.parse import urlparse, urljoin # Parse and manipulate URLs
9 |
10 | # ============================
11 | # 2. Third-Party Library Imports
12 | # ============================
13 |
14 | from flask import (
15 | Flask, # The core Flask class to create the application
16 | render_template, # Render HTML templates
17 | request, # Access incoming request data
18 | redirect, # Redirect responses to different routes
19 | url_for, # Build URLs for specific functions
20 | jsonify, # Return JSON responses
21 | session, # Manage user sessions
22 | flash # Display flashed messages to users
23 | )
24 | from flask_sqlalchemy import SQLAlchemy # ORM for database interactions
25 | from flask_migrate import Migrate # Handle database migrations
26 | from dotenv import load_dotenv # Load environment variables from a .env file
27 |
28 | # ============================
29 | # 3. Application Setup
30 | # ============================
31 |
32 | # Load environment variables from .env file
33 | # Uncomment the following line if you have a .env file to load environment variables
34 | # load_dotenv()
35 |
36 | # Initialize the Flask application
37 | app = Flask(__name__)
38 |
39 | # ============================
40 | # 4. Application Configuration
41 | # ============================
42 |
43 | # Configure the SQLite database URI
44 | app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///sidequests.db'
45 |
46 | # Disable modification tracking to save resources
47 | app.config['SQLALCHEMY_TRACK_MODIFICATIONS'] = False
48 |
49 | # Secret Key fetched from environment variables for security purposes
50 | app.secret_key = os.getenv('SECRET_KEY')
51 |
52 | # Initialize SQLAlchemy with the Flask app for ORM capabilities
53 | db = SQLAlchemy(app)
54 |
55 | # Initialize Flask-Migrate for handling database migrations
56 | migrate = Migrate(app, db)
57 |
58 | # ============================
59 | # 5. Database Models
60 | # ============================
61 |
62 | class Quest(db.Model):
63 | """
64 | Represents a Quest in the application.
65 |
66 | Attributes:
67 | id (int): Primary key identifier for the quest.
68 | name (str): The name of the quest.
69 | order (int): The display order of the quest.
70 | objectives (List[Objective]): A list of associated objectives.
71 | """
72 | id = db.Column(db.Integer, primary_key=True)
73 | name = db.Column(db.String(100), nullable=False)
74 | order = db.Column(db.Integer, default=0)
75 | # Establish a one-to-many relationship with Objective
76 | objectives = db.relationship('Objective', backref='quest', lazy=True)
77 |
78 | class Objective(db.Model):
79 | """
80 | Represents an Objective within a Quest.
81 |
82 | Attributes:
83 | id (int): Primary key identifier for the objective.
84 | title (str): The title or description of the objective.
85 | completed (bool): Status indicating if the objective is completed.
86 | order (int): The display order of the objective within its quest.
87 | list_id (int): Foreign key linking to the associated Quest.
88 | """
89 | id = db.Column(db.Integer, primary_key=True)
90 | title = db.Column(db.String(200), nullable=False)
91 | completed = db.Column(db.Boolean, default=False)
92 | order = db.Column(db.Integer, default=0)
93 | # Foreign key linking to the Quest model
94 | list_id = db.Column(db.Integer, db.ForeignKey('quest.id'), nullable=False)
95 |
96 | # ============================
97 | # 6. Database Initialization
98 | # ============================
99 |
100 | # Ensure all database tables are created
101 | with app.app_context():
102 | db.create_all()
103 |
104 | # ============================
105 | # 7. Helper Functions
106 | # ============================
107 |
108 | def is_safe_url(target):
109 | """
110 | Validates whether the target URL is safe for redirects.
111 |
112 | Args:
113 | target (str): The target URL to validate.
114 |
115 | Returns:
116 | bool: True if the URL is safe, False otherwise.
117 | """
118 | ref_url = urlparse(request.host_url)
119 | test_url = urlparse(urljoin(request.host_url, target))
120 | # Check if the netloc (network location) is the same as the host
121 | return test_url.netloc in [ref_url.netloc, request.host]
122 |
123 | def login_required(f):
124 | """
125 | Decorator to ensure that routes require user authentication.
126 |
127 | Args:
128 | f (function): The route function to wrap.
129 |
130 | Returns:
131 | function: The wrapped function that includes authentication check.
132 | """
133 | @wraps(f)
134 | def decorated_function(*args, **kwargs):
135 | # Check if the user is logged in by verifying the session
136 | if 'logged_in' not in session:
137 | # Store the next URL to redirect after successful login
138 | session['next_url'] = request.url
139 | return redirect(url_for('login'))
140 | return f(*args, **kwargs)
141 | return decorated_function
142 |
143 | # ============================
144 | # 8. Route Definitions
145 | # ============================
146 |
147 | @app.route('/login', methods=['GET', 'POST'])
148 | def login():
149 | """
150 | Handles user login by verifying credentials.
151 |
152 | GET: Renders the login page.
153 | POST: Processes login credentials and authenticates the user.
154 |
155 | Returns:
156 | Response: Redirects to the main page upon successful login or re-renders the login page with errors.
157 | """
158 | # If the user is already logged in, redirect to the main page
159 | if 'logged_in' in session:
160 | return redirect(url_for('root'))
161 |
162 | if request.method == 'POST':
163 | # Retrieve username and password from the submitted form
164 | username = request.form.get('username')
165 | password = request.form.get('password')
166 |
167 | # Fetch admin credentials from environment variables
168 | admin_username = os.getenv('ADMIN_USERNAME')
169 | admin_password = os.getenv('ADMIN_PASSWORD')
170 |
171 | # Validate credentials
172 | if username == admin_username and password == admin_password:
173 | # Set the session to indicate the user is logged in
174 | session['logged_in'] = True
175 | flash('You were successfully logged in.', 'success')
176 | # Retrieve the next URL to redirect to after login
177 | next_url = session.pop('next_url', None)
178 | return redirect(next_url or url_for('root'))
179 | else:
180 | # Flash an error message for invalid credentials
181 | flash('Invalid username or password.', 'danger')
182 |
183 | # Render the login template for GET requests or failed POST attempts
184 | return render_template('login.html')
185 |
186 | @app.route('/')
187 | @login_required
188 | def root():
189 | """
190 | Renders the main page displaying all quests.
191 |
192 | Requires:
193 | User to be authenticated.
194 |
195 | Returns:
196 | Response: The rendered 'list_index.html' template with all quests.
197 | """
198 | # Query all quests ordered by their 'order' attribute
199 | quests = Quest.query.order_by(Quest.order).all()
200 | # Render the template with the list of quests
201 | return render_template('list_index.html', lists=quests)
202 |
203 | @app.route('/list/