{"id":49441752,"url":"https://github.com/infraspecdev/mini-heroku","last_synced_at":"2026-04-29T20:36:29.451Z","repository":{"id":336020655,"uuid":"1147829283","full_name":"infraspecdev/mini-heroku","owner":"infraspecdev","description":"A Go-based mini PaaS inspired by Heroku, built as a mentorship project to explore container runtimes, CLI design, and networking fundamentals.","archived":false,"fork":false,"pushed_at":"2026-04-09T16:10:51.000Z","size":134,"stargazers_count":0,"open_issues_count":2,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-09T18:12:47.701Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/infraspecdev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-02T08:59:45.000Z","updated_at":"2026-03-30T16:53:46.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/infraspecdev/mini-heroku","commit_stats":null,"previous_names":["infraspecdev/mini-heroku"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/infraspecdev/mini-heroku","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infraspecdev%2Fmini-heroku","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infraspecdev%2Fmini-heroku/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infraspecdev%2Fmini-heroku/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infraspecdev%2Fmini-heroku/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/infraspecdev","download_url":"https://codeload.github.com/infraspecdev/mini-heroku/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infraspecdev%2Fmini-heroku/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32443567,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T20:22:27.477Z","status":"ssl_error","status_checked_at":"2026-04-29T20:22:26.507Z","response_time":110,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-29T20:36:25.747Z","updated_at":"2026-04-29T20:36:29.443Z","avatar_url":"https://github.com/infraspecdev.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mini Heroku (PaaS)\n**Duration:** 8 Weeks  \n**Team Size:** 2 Developers  \n**Focus:** Infrastructure, Systems Programming, Containerization\n\n## 1. Project Overview\nThe goal of this internship is to build a simplified **Platform as a Service (PaaS)** similar to Heroku or Vercel using the **Go** programming language.\n\nBy the end of this project, you will have built a system that allows a user to type a single command (e.g., `mini deploy .`) in their terminal, which will package their source code, run it on a server, and provide a live URL (e.g., `http://my-app.localhost`) to access it.\n\n### Core Learning Objectives\n*   **Containerization Internals:** Understanding how Docker works programmatically via the Go SDK.\n*   **Networking:** Understanding Reverse Proxies, DNS, and HTTP routing in Go.\n*   **Systems Design:** Managing state, logs, and processes in a distributed system.\n*   **CLI Design:** Building intuitive developer tools using the Cobra or any suited Go library.\n\n\n## 2. High-Level Architecture\nThe system consists of three main components:\n\n1.  **The CLI (Client):** A command-line tool running on the user's machine. It zips up source code and sends it to the server.\n2.  **The Controller (Server):** The \"brain\" of the operation. It receives code, instructs the Docker Daemon to build images/run containers, and stores application metadata (SQLite).\n3.  **The Reverse Proxy:** The entry point for HTTP traffic. It sits on port 80, looks at the incoming Host header (e.g., `blog.localhost`), and routes the request to the specific Docker container handling that app.\n\n### System Diagram\n\n```mermaid\nflowchart TD\n    subgraph \"User's Machine\"\n        CLI[Terminal / CLI Tool]\n        Browser[Web Browser]\n    end\n\n    subgraph \"Cloud VM\"\n        Proxy[Reverse Proxy]\n        API[Platform Controller / API]\n        DB[(SQLite DB)]\n        Docker[Docker Daemon]\n        App1[Container: App A]\n        App2[Container: App B]\n    end\n\n    %% Deployment Flow\n    CLI -- \"1. mini deploy (zip)\" --\u003e API\n    API -- \"2. Update State\" --\u003e DB\n    API -- \"3. Build \u0026 Run\" --\u003e Docker\n    Docker -- \"4. Spin up\" --\u003e App1\n    Docker -- \"4. Spin up\" --\u003e App2\n\n    %% Traffic Flow\n    Browser -- \"1. Request: app-a.com\" --\u003e Proxy\n    Proxy -. \"2. Query IP\" .- API\n    Proxy -- \"3. Forward Request\" --\u003e App1\n    Proxy -- \"3. Forward Request\" --\u003e App2\n\n    %% Styling\n    style CLI fill:#e1f5fe,stroke:#01579b\n    style API fill:#e8f5e9,stroke:#2e7d32\n    style Proxy fill:#fff3e0,stroke:#ef6c00\n    style Docker fill:#f3e5f5,stroke:#7b1fa2\n```\n\n## 3. Example Walkthrough\n\nTo understand the project better, here is how a developer will eventually use your platform:\n\n### User Perspective (The CLI)\nImagine a developer has a simple web app in a folder. They will use your tool like this:\n```bash\n$ cd my-web-app\n$ mini deploy .\n[1/3] Zipping source code... Done.\n[2/3] Building image \"app-blue-sky\"... (Docker build output follows)\n[3/3] Starting container... Done.\n\n🚀 Your app is live at: http://blue-sky.localhost\n```\n\n### Behind the Scenes (The Server Logic)\nInternally, your **Controller** code will look something like this (Go code):\n```go\nfunc handleDeploy(w http.ResponseWriter, r *http.Request) {\n    // 1. Receive the code zip file from the CLI\n    // 2. Extract it to a temporary folder\n    // 3. Call Docker SDK: \n    // docker.ImageBuild(ctx, buildContext, types.ImageBuildOptions{...})\n    \n    // 4. Start the container and get its internal IP\n    // 5. Tell the Proxy: \"Route 'blue-sky.localhost' to this IP\"\n}\n```\n\n## 4. Weekly Roadmap\n\n### Phase 1: Getting Started with Docker (Weeks 1-2)\n*Goal: Learn to control Docker with Go.*\n\n#### **Week 1: Docker SDK Fundamentals**\nInstead of typing `docker run`, you will write Go code to do it for you.\n*   **Objectives:**\n    *   Set up the Go development environment.\n    *   Connect to the Docker Daemon via the official Go SDK (`github.com/docker/docker/client`).\n    *   Write a Go program to pull an image and start a container.\n    *   List currently running containers and their ports via code.\n*   **Deliverable:** A Go binary that spins up a \"Hello World\" container and prints its ID.\n\n#### **Week 2: The Builder**\nTurning raw source code into a runnable image.\n*   **Objectives:**\n    *   Create a sample user app (e.g., a simple Go web server with a `Dockerfile`).\n    *   Implement a Go API endpoint that accepts a `.tar.gz` of source code.\n    *   Use the Docker SDK to `ImageBuild` an image from that source code.\n*   **Deliverable:** A Go function that returns a Docker Image ID from a source archive.\n\n### Phase 2: Moving to the Cloud (Week 3)\n*Goal: Moving from \"It works on my machine\" to \"It works on the Cloud\".*\n\n#### **Week 3: Cloud Migration \u0026 CI/CD**\nInstead of running the server locally, we will deploy it to a real Cloud VM.\n*   **Objectives:**\n    *   **Provisioning:** SSH into the provided Cloud VM and install Docker and Go.\n    *   **CI/CD Pipeline:** Create a GitHub Action that triggers on every `git push`:\n        1.  Builds the Go binary.\n        2.  Transfers it to the VM (via SCP/SSH).\n        3.  Restarts the systemd service.\n*   **Deliverable:** A pipeline where merging code automatically updates the live server on the VM.\n\n\n### Phase 3: Building the Core Logic (Weeks 4-5)\n*Goal: Routing traffic and managing persistence in a production environment.*\n\n#### **Week 4: The Reverse Proxy**\nRouting requests from the internet to the correct container.\n*   **Objectives:**\n    *   Implement dynamic routing using `httputil.ReverseProxy`.\n    *   Configure DNS (or `/etc/hosts` for testing) to point subdomains to the VM's public IP.\n    *   Handle `app-a.vm-ip.nip.io` -\u003e Container A.\n*   **Deliverable:** Accessing containers via public URLs.\n\n#### **Week 5: State \u0026 Persistence**\nRemembering what is running.\n*   **Objectives:**\n    *   Implement SQLite for state management.\n    *   Ensure database persistence across deployments (if you deploy a new server version, the DB should remain intact on the VM).\n*   **Deliverable:** A restartable platform on the cloud.\n\n\n### Phase 4: Finishing Touches (Weeks 6-8)\n*Goal: Tying it all together for the user.*\n\n#### **Week 6: The CLI Tool**\n*   **Objectives:**\n    *   Build the `mini` CLI.\n    *   Add a config command to point the CLI to the Cloud VM URL (e.g., `mini config set-host http://1.2.3.4`).\n    *   Implement `mini deploy` to upload code to the remote server.\n*   **Deliverable:** Deploying an app from a laptop to the Cloud VM.\n\n#### **Week 7: Observability \u0026 Reliability**\n*   **Objectives:**\n    *   Implement `mini logs` to stream logs from the remote container.\n    *   **Challenge:** Add basic authentication (API Key) so only authorized users can deploy.\n*   **Deliverable:** Secure and observable deployments.\n\n#### **Week 8: Documentation \u0026 Demo**\n*   **Objectives:**\n    *   Final code cleanup.\n    *   **The Demo:** You will present the project by deploying a fresh app to the live Cloud VM.\n\n\n## 5. Technical Stack\n*   **Language:** Go (Golang)\n*   **Container Engine:** Docker (via Go SDK)\n*   **Database:** SQLite\n*   **CLI Framework:** Cobra\n*   **Proxy:** Go `net/http/httputil`\n\n## 6. Working Agreements \u0026 Expectations\nWe treat this internship as a simulation of a real engineering environment.\n\n*   **The 3-Hour Rule:** If you are stuck on a specific error for more than 3 hours, stop and ask for help. We want you to struggle enough to learn, but not enough to burn out.\n*   **Quality \u003e Speed:** It is better to have a fully working \"Hello World\" deployment than a broken complex system.\n*   **Understanding is Key:** During code reviews, we will ask \"Why?\". You must be able to explain every line of code you write.\n*   **Collaborate:** You are a team. Don't split the work in silos (e.g., \"I do server, you do CLI\"). Pair program on the hard parts.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finfraspecdev%2Fmini-heroku","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finfraspecdev%2Fmini-heroku","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finfraspecdev%2Fmini-heroku/lists"}