puzzle.unturf.com/README.rst

=========================================================
PyraPuzzle - A Daily Puzzle Game Built with Pyramid
=========================================================

**PyraPuzzle** is a **public domain** web application built on the `Pyramid <https://trypyramid.com>`_ framework. It offers daily puzzles for users to enjoy and compete on leaderboards. The application supports guest users, registered users, and administrative functions for managing puzzles and users.

Key Features
============

- **Daily Puzzles**: Fresh puzzles every day in various sizes (3x3, 4x4, 5x5).
- **Guest and Registered Users**: Play as a guest or register to track your progress.
- **Passwordless Authentication**: Secure login via email verification codes (OTP).
- **Leaderboards**: Compete with others on daily leaderboards and global rankings.
- **User Profiles**: Customize your profile and view statistics.
- **Admin Tools**: Upload puzzles, manage users, and monitor the application.
- **Persistent Data**: Application data and secrets are stored in a mounted `data/` directory.

Git Repository
==============

The project is maintained at:

- `PyraPuzzle Git Repo <https://git.unturf.com/engineering/unturf/puzzle.unturf.com>`_

Since this project is in the public domain, you can adapt and redistribute it freely.

Configuration via Environment
=============================

PyraPuzzle fetches settings from environment variables with sensible defaults:

- ``PYRAPUZZLE_SECRET``  
  The secret key for session signing.  
  If missing, PyraPuzzle automatically generates a **random 64-character** string at runtime, saves it to ``data/secret.txt``, which will log out all users if changed.

- ``PYRAPUZZLE_DB_URL``  
  Connection string for the database. Default: ``sqlite:///data/puzzle_game.db``.

- ``PYRAPUZZLE_HOST`` and ``PYRAPUZZLE_PORT``  
  The host and port to serve on. Defaults: ``0.0.0.0`` (host), ``6543`` (port).

- ``PYRAPUZZLE_SMTP_HOST`` and ``PYRAPUZZLE_SMTP_PORT``  
  SMTP server details for sending emails. Defaults: ``localhost:25``.

Local Setup
===========

1. **Clone the Project**

   .. code-block:: bash

      git clone https://git.unturf.com/engineering/unturf/puzzle.unturf.com.git
      cd puzzle.unturf.com

2. **Create a Virtual Environment**

   .. code-block:: bash

      python3 -m venv venv
      source venv/bin/activate  # On Linux/Mac
      # On Windows:
      venv\Scripts\activate.bat

3. **Install Dependencies**

   .. code-block:: bash

      pip install -r requirements.txt

4. **Run the Application**

   .. code-block:: bash

      # Optionally set PYRAPUZZLE_SECRET to a fixed value
      export PYRAPUZZLE_SECRET="YOUR_OWN_LONG_RANDOM_STRING"
      python app.py

   If ``PYRAPUZZLE_SECRET`` is **not** set, the app automatically generates a 64-character secret at runtime and saves it to ``data/secret.txt``.

5. **Access the Application**

   Open your browser and navigate to `http://localhost:6543` or `http://<HOST>:<PORT>` based on your environment variables.

Docker Deployment
=================

A Dockerfile is provided to facilitate containerized deployment. Below is an example Dockerfile that:

- Uses **Waitress** to run PyraPuzzle.
- Defines a **volume** for the `data/` directory to persist application data.

.. code-block:: dockerfile

   # Dockerfile for PyraPuzzle

   FROM python:3.9-slim

   WORKDIR /app

   # Copy application code
   COPY . /app

   # Install Python dependencies
   RUN pip install --no-cache-dir -r requirements.txt

   # Expose the application port
   EXPOSE 6543

   # Ensure the data directory exists and is mounted as a volume
   VOLUME /app/data

   # Set environment variables (override these in production)
   ENV PYRAPUZZLE_HOST="0.0.0.0"
   ENV PYRAPUZZLE_PORT="6543"
   ENV PYRAPUZZLE_DB_URL="sqlite:///data/puzzle_game.db"
   ENV PYRAPUZZLE_SMTP_HOST="localhost"
   ENV PYRAPUZZLE_SMTP_PORT="25"

   # Start the application
   CMD ["python", "app.py"]

**Notes:**

- **Data Persistence**: The `data/` directory is where the database and secret files are stored. Mount this directory as a volume to persist data between container restarts.

- **Secrets**: In production, set `PYRAPUZZLE_SECRET` to a fixed value to avoid invalidating user sessions.

**Building and Running with Docker:**

.. code-block:: bash

   # Build the Docker image
   docker build -t pyrapuzzle .

   # Run the Docker container
   docker run -d -p 6543:6543 \
      -v $(pwd)/data:/app/data \
      --name pyrapuzzle \
      pyrapuzzle

   # For Windows PowerShell, use:
   docker run -d -p 6543:6543 `
      -v ${PWD}/data:/app/data `
      --name pyrapuzzle `
      pyrapuzzle

**Environment Variables in Docker:**

You can pass environment variables to the Docker container using the `-e` flag:

.. code-block:: bash

   docker run -d -p 6543:6543 \
      -v $(pwd)/data:/app/data \
      -e PYRAPUZZLE_SECRET="YOUR_OWN_LONG_RANDOM_STRING" \
      -e PYRAPUZZLE_SMTP_HOST="smtp.example.com" \
      -e PYRAPUZZLE_SMTP_PORT="587" \
      --name pyrapuzzle \
      pyrapuzzle

OpenAPI Documentation
=====================

PyraPuzzle does not currently provide an OpenAPI specification. Future plans may include API endpoint documentation for integration purposes.

License and Public Domain
=========================

This project is in the public domain. You are free to use, adapt, and redistribute it without attribution or additional licensing.

If you find PyraPuzzle helpful, feel free to contribute back or share your enhancements!

Support and Contact
===================

- **Issues**: Please open tickets at the `PyraPuzzle Git Repo <https://git.unturf.com/engineering/unturf/puzzle.unturf.com>`_.
- **Contributions**: If you register an account, let us know, and we will grant you developer access to contribute.
- **General Inquiries**: Reach out to the maintainers directly.

Enjoy and happy puzzling!