Skip to main content

​
Get Up and Running Fast

This guide will get you from zero to a running Maths Society Platform in minimal steps. Perfect for trying out the platform or starting local development.
This quickstart is for development only. For production deployment, see the Installation Guide.

​
Prerequisites

Before you begin, ensure you have:

Python 3.8+

Check with python --version or python3 --version

pip

Python package installer (usually included with Python)

Git

For cloning the repository

PostgreSQL (Optional)

SQLite works for quick testing, PostgreSQL recommended for development

​
Quick Setup

1

Clone the Repository

Clone the project and navigate into the directory:
git clone https://github.com/yousuf-shahzad/maths-soc-source.git
cd maths-soc-source
You can also fork the repository first if you plan to make customizations.
2

Create Virtual Environment

Create and activate a Python virtual environment:
python -m venv venv
venv\Scripts\activate
You should see (venv) in your terminal prompt when the environment is activated.
3

Install Dependencies

Install all required Python packages:
pip install -r requirements.txt
This installs:
  • Flask 2.1.0 and extensions
  • SQLAlchemy 1.4.31
  • PostgreSQL driver (psycopg2)
  • CKEditor, WTForms, and other dependencies
Installation may take 1-2 minutes depending on your connection speed.
4

Configure Environment

Create a .env file in the project root with basic configuration:
.env
# Secret key for session management
SECRET_KEY=dev-secret-key-change-in-production

# Database configuration (SQLite for quickstart)
DATABASE_TYPE=sqlite
DB_NAME=mathsoc

# Environment settings
FLASK_ENV=development
APP_ENVIRONMENT=development

# Logging
LOG_TO_STDOUT=false
The SECRET_KEY shown here is for development only. Never use this in production!
5

Initialize the Database

Set up the database schema and create a default admin user:
python init_db.py
The init_db.py script:
  • Creates all database tables
  • Creates a default admin user
  • Seeds initial data for testing
Default admin credentials:
  • Username: admin
  • Password: admin123
Change this password immediately after first login!
6

Run the Application

Start the Flask development server:
python run.py
You should see output like:
* Serving Flask app 'app'
* Debug mode: on
* Running on http://127.0.0.1:5000
Your Maths Society Platform is now running! Open http://127.0.0.1:5000 in your browser.

​
Verify Installation

Test that everything is working correctly:
1

Access the Homepage

Navigate to http://127.0.0.1:5000 - you should see the Maths Society homepage
2

Login as Admin

Click “Login” and use the default credentials:
  • Username: admin
  • Password: admin123
3

Access Admin Panel

After login, navigate to the admin area to verify admin functionality
4

Check Health Endpoints

Test the health check endpoints:
curl http://127.0.0.1:5000/healthz
curl http://127.0.0.1:5000/readyz
Both should return {"status": "ok"} or {"status": "ready"}

​
Application Structure

Here’s what you’ve just set up:
run.py
from app import create_app

app = create_app('development')

if __name__ == '__main__':
    debug_mode = os.environ.get('FLASK_ENV') != 'production'
    app.run(debug=debug_mode, host='127.0.0.1', port=5000)
The application uses the factory pattern defined in app/__init__.py:
app/__init__.py (simplified)
def create_app(config_name="development"):
    config_class = get_config(config_name)
    app = Flask(__name__)
    app.config.from_object(config_class)
    
    # Initialize extensions
    db.init_app(app)
    login_manager.init_app(app)
    migrate.init_app(app, db)
    ckeditor.init_app(app)
    limiter.init_app(app)
    
    # Register blueprints
    app.register_blueprint(auth_bp)
    app.register_blueprint(main_bp)
    app.register_blueprint(profile_bp)
    app.register_blueprint(admin_bp)
    
    return app

​
Next Steps

Explore Features

  • Create challenges
  • Set up a competition
  • Write articles and newsletters
  • Customize the platform

Development Tips

  • Run tests with pytest
  • Enable debug mode for development
  • Use Flask-Migrate for schema changes
  • Check logs in app.log

Configuration

  • Review config.py for settings
  • Configure email notifications
  • Set up rate limiting
  • Customize CSP policies

Production Deployment

  • Read the Installation Guide
  • Set up PostgreSQL
  • Configure Gunicorn
  • Deploy with proper secrets

​
Common Issues

If port 5000 is occupied, you can change it in run.py:
run.py
app.run(debug=debug_mode, host='127.0.0.1', port=5001)
Or set the FLASK_RUN_PORT environment variable.
If using PostgreSQL and seeing connection errors:
  1. Verify PostgreSQL is running: pg_isready
  2. Check database exists: psql -l | grep mathsoc
  3. Verify credentials in .env file
  4. Try SQLite instead by setting DATABASE_TYPE=sqlite
If you see ModuleNotFoundError:
  1. Ensure virtual environment is activated (look for (venv) in prompt)
  2. Reinstall dependencies: pip install -r requirements.txt
  3. Try upgrading pip: pip install --upgrade pip
If CSS/images aren’t loading:
  1. Check Flask is serving from the correct directory
  2. Verify app/static directory exists
  3. Clear browser cache
  4. Check browser console for CSP errors

​
Development Workflow

For ongoing development:
1

Start Development Server

python run.py
The server auto-reloads on code changes in debug mode.
2

Make Database Changes

When modifying models:
flask db migrate -m "Description of changes"
flask db upgrade
3

Run Tests

Before committing:
pytest
4

Build Documentation

Generate Sphinx docs:
cd docs
pip install -r requirements.txt
make html
Enable debug mode to get detailed error pages and automatic reloading. Just ensure FLASK_ENV=development is set in your .env file.

​
Getting Help

Need assistance?
Congratulations! You now have a working Maths Society Platform. Start exploring the admin panel to create challenges and customize your platform.

Build docs developers (and LLMs) love

Get started for freeTalk to us