Overview

The FromFirstPrinciples repository serves a dual purpose: it is both a comprehensive collection of long-form technical articles grounded in first-principles thinking, and the source code for a high-performance, containerized development environment designed for C++, Python, and Rust programming. This meticulously crafted environment aims to tackle the common challenges of development setup by ensuring that the code can be executed in a consistent and reliable setting, thus resolving the perennial "it works on my machine" dilemma.

Core Philosophy

This project operates under several guiding principles:

• First-Principles Thinking: The focus is on truly understanding the underlying technology. Instead of merely utilizing tools at face value, the project examines their foundational workings, from the Linux kernel features enabling containers to the HTTP protocols that facilitate web APIs.
• Absolute Reproducibility: The entire development environment is defined as code using a Dockerfile and accompanying shell scripts. This ensures that any developer can set up an identical environment on any machine that supports Docker, effectively eliminating environmental drift and configuration issues.
• High Performance as a Standard: Pre-packaged binaries are eschewed in favor of a custom-built environment that features modern toolchains, like GCC and experimental Python versions (e.g., nogil). This approach provides direct access to the latest innovations and optimizations.

Getting Started

The process of building and running the development environment is designed to be straightforward, though the initial setup may require a significant amount of time due to the compilation of toolchains from source.

Clone the Repository

To begin, clone the repository to the local machine and navigate into the project directory:

git clone https://github.com/InfiniteConsult/FromFirstPrinciples.git
cd FromFirstPrinciples

Prepare the Host System

Execute the host setup script to install Docker, which powers the entire development environment. This script necessitates sudo privileges:

bash install-docker.sh

Configure the Environment (Optional)

For users wishing to customize the setup, such as enabling NVIDIA GPU support for machine learning tasks, the configure.sh script can be employed:

# Example: To enable GPU support
bash configure.sh --enable-gpu

Build the Docker Image

The following script compiles the container image as defined in the Dockerfile. This initial build is a one-time activity and may take considerable time; however, subsequent builds will leverage cached layers:

bash build-dev.sh

Run the Container

Start the container using this command, which will mount essential local directories and expose the required service ports. All services, like SSH, JupyterLab, and the Article Viewer, will start in the background:

bash dev-container.sh

Access Your Services

Upon successful startup of the container, various services can be accessed:

• SSH / IDE Connection: Connect to the container's shell directly or through a remote-friendly IDE for a full-featured development experience.

  ssh -p 10200 your_username@127.0.0.1
  

• JupyterLab: Access the interactive web-based IDE for data science and prototyping at https://127.0.0.1:10201.
• Article Viewer: Read articles via the self-hosted viewer at https://127.0.0.1:10202.

Repository Structure

The repository is thoughtfully organized into several directories:

Core Environment Files (Root /)

These critical files are what drive and control the containerized environment, including:

• Dockerfile: The blueprint for the container image.
• build-dev.sh: A script to build the Docker image.
• dev-container.sh: A script to run the container.
• entrypoint.sh: The script that executes inside the container at startup.
• configure.sh & dev.conf: A system for customizing the build options.

For a complete understanding of how these files operate, it is recommended to read the article located in articles/0002_docker_dev_environment/.

articles/

This directory comprises the repository's knowledge base, containing all source code and text for technical articles, with each sub-folder representing an individual article.

viewer/

Houses the source code for a FastAPI web application that serves and renders the content from the articles/ directory.

repos/

This is a persistent, mounted workspace ideal for cloning personal Git repositories and conducting development work while keeping it separate from the core repository's source code.

data/

Serves as a persistent storage directory for files that need to persist across container runs, such as configuration files and self-signed TLS certificates for various services.