add readme.md

readme.md

@@ -0,0 +1,74 @@
+# www.0_timeline.org
+
+This repository contains the source code and deployment configuration for the [0_timeline.org](https://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:
+    ```bash
+    python -m venv venv
+    source venv/bin/activate
+    ```
+3.  Install all dependencies:
+    ```bash
+    pip install -r requirements.txt
+    ```
+4.  To preview your changes locally, run the MkDocs development server:
+    ```bash
+    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.