web-hosts/domains/coppertone.tech/docs/project-plan/phases/Phase-1-Foundation-and-Infrastructure.md

Phase 1 Breakdown: Foundation & Infrastructure Setup

This phase is dedicated to establishing the foundational infrastructure for the entire project. The goal is to create a robust, version-controlled, and automated development environment before any significant feature development begins.

---

Task 1.1: Initialize Git Repository

This is the first step in tracking our project's history. A clean and comprehensive version control setup is crucial.

• 1.1.1. Initialize Git:
  • Run git init in the project root directory.
• 1.1.2. Create .gitignore:
  • Create a .gitignore file in the root.
  • Add entries for common Node.js, Vue.js, Go, and system files that should not be committed to the repository.
• 1.1.3. Initial Commit:
  • Add all initial project files to staging: git add .
  • Make the first commit: git commit -m "Initial commit: project structure and plan"

---

Task 1.2: Containerization with Podman

We will use Podman to create consistent, isolated environments for our applications.

• 1.2.1. Frontend Containerfile:
  • Create a file named Containerfile in the frontend application's subdirectory.
  • Implement a multi-stage build to keep the final image small and secure:
    • Build Stage: Use a node:lts image. Copy package.json and package-lock.json, run npm install, copy the source code, and run npm run build.
    • Production Stage: Use a lightweight web server image like nginx:stable-alpine. Copy the built assets from the build stage into the Nginx public directory (/usr/share/nginx/html). Copy over a custom Nginx configuration file to handle Vue Router's history mode.
• 1.2.2. Backend Containerfile (for Go Functions):
  • Create Containerfiles for individual Go serverless functions/microservices.
  • Use a golang:1.25-alpine or similar base image for building Go binaries.
  • Optimize for small, secure images (e.g., using scratch or alpine for the final runtime image with just the Go binary).
• 1.2.3. Podman Compose Configuration:
  • Create a podman-compose.yml file in the project root.
  • Define services for each part of our stack: frontend, individual Go backend functions, database (PostgreSQL), Gitea, Matrix (Synapse), and a self-hosted email server.
  • Ensure podman-compose.yml is optimized for orchestrating Go serverless functions, database, communication services, and other planned components.

---

Task 1.3: Vue.js Project Initialization

This involves setting up the frontend application with all the necessary tools and libraries.

• 1.3.1. Scaffold the Vue App:
  • Run npm init vue@latest.
  • When prompted, select the following options:
    • Project name: frontend (or similar)
    • Add TypeScript: Yes
    • Add JSX Support: No
    • Add Vue Router for Single Page Application development: Yes
    • Add Pinia for state management: Yes
    • Add Vitest for Unit Testing: Yes
    • Add an End-to-End Testing Solution: Cypress
    • Add ESLint for code quality: Yes
    • Add Prettier for code formatting: Yes
  • Post-scaffolding, install Helia for IPFS integration and establish basic Markdown content rendering capabilities.
• 1.3.2. Integrate Tailwind CSS:
  • Navigate into the new frontend directory.
  • Install Tailwind CSS and its peer dependencies: npm install -D tailwindcss postcss autoprefixer
  • Generate the Tailwind and PostCSS configuration files: npx tailwindcss init -p
  • Configure Tailwind's tailwind.config.js to scan Vue components for classes.
  • Create a main CSS file (src/assets/main.css) and import the Tailwind layers.

---

Task 1.4: Gitea & Gitea Actions CI Setup

Automating our build and test process is key to an enterprise-grade workflow.

• 1.4.1. Deploy Gitea:
  • Add a gitea service to the podman-compose.yml.
  • Use the official gitea/gitea image.
  • Map ports (e.g., 3000:3000 for the web UI, 2222:22 for SSH).
  • Use Podman volumes to persist Gitea's data (/var/lib/gitea) and configuration (/etc/gitea).
  • After starting the service, complete the setup via the Gitea web UI.
• 1.4.2. Push Project to Gitea:
  • Create a new repository in the Gitea UI.
  • Add the Gitea repository as a remote to your local project: git remote add origin <gitea_repo_url>
  • Push the initial commit: git push -u origin main
• 1.4.3. Configure Gitea Actions for CI/CD:
  • Enable Gitea Actions on the Gitea instance.
  • Create an initial .gitea/workflows/build-frontend.yml file in the project root (or appropriate subdirectory).
  • Define a simple workflow that triggers on push events to develop or PRs to develop.
  • Add steps to:
    1. Clone the repository.
    2. Navigate to the frontend directory.
    3. Set up Node.js.
    4. Install dependencies (npm install).
    5. Run the build (npm run build).
    6. (Optional) Run tests (npm run test:unit).
  • Future steps will include separate workflows for Go backend functions and deployment to testing and main branches.
  • Commit and push this file to trigger the first automated build.