1_general_forum/readme.md

www.0_timeline.org

This repository contains the source code and deployment configuration for the 0_timeline.org website.

📍 Objective (What It Is)

0_timeline.org is a public-facing static website that serves as the primary transparency layer for the Smartup Zero project. It automatically mirrors the content of this Forgejo repository and serves three main purposes:

• Transparency Layer: Showing the world what Smartup Zero is building (ONLIFE), who's involved, and the current state of progress.
• Official Smartup Business Plan (OSBP): Publishing the "why" and "what" of the project, derived from our community decisions.
• Recruitment Portal: Displaying our team structure, open roles, and the process for joining the project.

🔧 Deployment Pipeline (How It Works)

This project is automatically deployed to Clever Cloud on every push to the master branch. The process leverages Clever Cloud's Python App Hosting to achieve a fully automated build and deployment pipeline.

The end-to-end flow is as follows:

1. Push to Forgejo: A developer pushes new commits to the master branch of this repository.
2. Webhook Trigger: Clever Cloud detects the new commit and starts a new deployment instance.
3. Dependency Installation: The server installs all Python packages listed in requirements.txt. This includes mkdocs and its plugins, the gunicorn web server, and the setuptools build tool.
4. Custom Build Step: Clever Cloud executes the goal defined in the PYTHON_SETUP_PY_GOAL environment variable (mkdocs).
   • This triggers our custom setup.py script.
   • The script runs the command mkdocs build, which compiles all Markdown from the docs/ directory into a static HTML site in a new site/ directory.
5. Application Start: After the build is complete, Clever Cloud starts the application server.
   • It uses gunicorn as the backend, as defined by the CC_PYTHON_BACKEND variable.
   • Gunicorn is instructed to run the WSGI application found in server.py (via the CC_PYTHON_MODULE variable).
6. Serving Files: The Python script server.py uses the WhiteNoise library to efficiently serve the static files from the site/ directory that was just created. The site is now live.

🛠️ Key Files & Configuration

This setup relies on a few key files to work correctly:

• mkdocs.yml: Standard configuration for the MkDocs site generator. Defines site structure, navigation, and theme.
• docs/: Contains all the raw Markdown content for the website. This is the primary folder for content editors.
• requirements.txt: Lists all Python dependencies. Crucially, it includes:
  • Site generator plugins (mkdocs, mkdocs-material, etc.).
  • The build tool (setuptools) needed to run our custom build script.
  • The serving tools (gunicorn, whitenoise) needed to run the live web server.
• setup.py: A standard Python build script that we use as a build hook. It defines a custom command (mkdocs) that runs the mkdocs build process.
• server.py: A minimal Python web application. Its only job is to use the WhiteNoise library to serve the static files generated by MkDocs. This script provides the WSGI-compatible application that Clever Cloud's Python hosting requires.

🎯 Rationale (Why This Setup?)

The deployment configuration for this project may seem complex for a static site. This specific approach was chosen to overcome limitations of the Clever Cloud platform.

Why not use a standard "Static Site" deployment?

Clever Cloud's static site buildpack automatically detects MkDocs and tries to run mkdocs build. However, it does not install dependencies from requirements.txt first. This causes the build to fail if you use any custom themes or plugins (like mkdocs-material).

Why not just run python -m http.server in a Python app?

The standard Python hosting on Clever Cloud is designed for production use and expects a robust WSGI server (like Gunicorn or uWSGI). It will not run a simple development server like http.server.

Our current solution is the ideal middle ground: It uses the Python App environment, which gives us full control to install all our dependencies, while the server.py script provides the simple-but-necessary WSGI interface that the platform requires.

✍️ How to Contribute

1. Clone this repository.
2. Create and activate a Python virtual environment:

   python -m venv venv
   source venv/bin/activate
   

3. Install all dependencies:

   pip install -r requirements.txt
   

4. To preview your changes locally, run the MkDocs development server:

   mkdocs serve
   

5. Open your browser to http://127.0.0.1:8000 to see the live-reloading site.
6. Make your changes to the Markdown files in the docs/ directory.
7. Once you are happy with your changes, commit them and push to the master branch. The deployment process is fully automatic from there.