Initial commit
This commit is contained in:
243
README.md
Normal file
243
README.md
Normal file
@@ -0,0 +1,243 @@
|
||||
# Demo: Portfolio Site
|
||||
|
||||
Personal portfolio website built with Astro (frontend) and Hono (API layer), consuming Directus CMS for content management.
|
||||
|
||||
## Tech Stack
|
||||
|
||||
- **Frontend**: [Astro](https://astro.build) - Fast, modern static site framework with SSR
|
||||
- **API**: [Hono](https://hono.dev) - Lightweight, ultrafast web framework for TypeScript
|
||||
- **CMS**: [Directus](https://directus.io) - Headless CMS (from infrastructure layer)
|
||||
- **Styling**: Tailwind CSS
|
||||
|
||||
## Purpose
|
||||
|
||||
This demo showcases:
|
||||
- ✅ Building a content-driven website with modern frameworks
|
||||
- ✅ Clean API layer pattern between frontend and CMS
|
||||
- ✅ Server-side rendering with Astro
|
||||
- ✅ TypeScript throughout the stack
|
||||
- ✅ Consuming shared infrastructure (Directus)
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────┐
|
||||
│ Demo: Portfolio Site │
|
||||
│ Domains: portfolio.b28.dev, api.b28.dev │
|
||||
├──────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ Astro │─────▶│ Hono API │ │
|
||||
│ │ Frontend │ │ (middleware) │ │
|
||||
│ └──────────────┘ └──────────────┘ │
|
||||
│ │ │ │
|
||||
│ └──────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌──────────────┐ │
|
||||
│ │ Directus │ (external) │
|
||||
│ │ CMS/API │ │
|
||||
│ └──────────────┘ │
|
||||
│ │
|
||||
└──────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Features
|
||||
|
||||
### Content Pages
|
||||
- **Home** (`/`) - Landing page with profile info
|
||||
- **Work** (`/work`) - Portfolio projects showcase
|
||||
- **Blog** (`/blog`) - Blog posts from Directus
|
||||
- **Demos** (`/demos`) - Catalog of all demo projects
|
||||
|
||||
### API Endpoints
|
||||
The Hono API acts as a middleware layer:
|
||||
- `GET /health` - Health check
|
||||
- `GET /api/posts` - Blog posts
|
||||
- `GET /api/work` - Work projects
|
||||
- `GET /api/demos` - Demo catalog
|
||||
- `GET /api/profile` - Profile data
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Docker and Docker Compose
|
||||
- Access to Directus infrastructure (see [portfolio-infrastructure](../../infrastructure/directus))
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Set up Infrastructure First
|
||||
|
||||
Before running this demo, ensure the Directus infrastructure is running:
|
||||
|
||||
```bash
|
||||
cd ../../infrastructure/directus
|
||||
cp .env.example .env
|
||||
# Edit .env with your values
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### 2. Configure Environment
|
||||
|
||||
```bash
|
||||
# Copy environment template
|
||||
cp .env.example .env
|
||||
|
||||
# Edit .env
|
||||
DIRECTUS_URL=http://localhost:8055 # or https://directus.b28.dev
|
||||
PUBLIC_API_URL=http://localhost:3000 # or https://api.b28.dev
|
||||
```
|
||||
|
||||
### 3. Start Demo
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### 4. Access
|
||||
|
||||
- **Frontend**: http://localhost:4321
|
||||
- **API**: http://localhost:3000
|
||||
|
||||
## Development
|
||||
|
||||
### Running Locally (without Docker)
|
||||
|
||||
#### API Development
|
||||
|
||||
```bash
|
||||
cd api
|
||||
npm install
|
||||
npm run dev # Runs on http://localhost:3000
|
||||
```
|
||||
|
||||
#### Frontend Development
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm install
|
||||
npm run dev # Runs on http://localhost:4321
|
||||
```
|
||||
|
||||
### Making Changes
|
||||
|
||||
**Frontend**:
|
||||
- Edit files in `frontend/src/`
|
||||
- Astro supports hot reload
|
||||
|
||||
**API**:
|
||||
- Edit files in `api/src/`
|
||||
- Hono is lightweight and fast to restart
|
||||
|
||||
**Content**:
|
||||
- Log into Directus (https://directus.b28.dev or http://localhost:8055)
|
||||
- Edit collections directly
|
||||
- Changes reflect immediately via API
|
||||
|
||||
## Deployment to Coolify
|
||||
|
||||
### Prerequisites
|
||||
1. Directus infrastructure must be deployed first
|
||||
2. Note the Directus URL (e.g., `https://directus.b28.dev`)
|
||||
|
||||
### Steps
|
||||
|
||||
1. **Create New Resource** in Coolify
|
||||
- Type: Docker Compose
|
||||
- Source: Git repository (this repo)
|
||||
|
||||
2. **Set Environment Variables**:
|
||||
```
|
||||
DIRECTUS_URL=https://directus.b28.dev
|
||||
PUBLIC_API_URL=https://api.b28.dev
|
||||
```
|
||||
|
||||
3. **Configure Domains**:
|
||||
- API: `api.b28.dev`
|
||||
- Frontend: `portfolio.b28.dev` or `b28.dev`
|
||||
|
||||
4. **Deploy**
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
portfolio-site/
|
||||
├── api/ # Hono API backend
|
||||
│ ├── src/
|
||||
│ │ ├── index.ts # Main API routes
|
||||
│ │ └── directus.ts # Directus client
|
||||
│ ├── Dockerfile
|
||||
│ └── package.json
|
||||
│
|
||||
├── frontend/ # Astro frontend
|
||||
│ ├── src/
|
||||
│ │ ├── pages/ # Route pages
|
||||
│ │ ├── components/ # Reusable components
|
||||
│ │ ├── layouts/ # Page layouts
|
||||
│ │ └── lib/ # Utilities
|
||||
│ ├── Dockerfile
|
||||
│ └── package.json
|
||||
│
|
||||
└── docker-compose.yml # Orchestration
|
||||
```
|
||||
|
||||
## Why This Architecture?
|
||||
|
||||
### Hono as Middleware
|
||||
Instead of calling Directus directly from the frontend:
|
||||
- ✅ **Clean separation**: Frontend doesn't need to know about Directus details
|
||||
- ✅ **Data transformation**: API can reshape data for frontend needs
|
||||
- ✅ **Caching**: API layer can add caching
|
||||
- ✅ **Security**: Directus credentials stay server-side
|
||||
- ✅ **Flexibility**: Can add business logic without touching frontend
|
||||
|
||||
### Astro for Frontend
|
||||
- ⚡ **Fast**: Static pages with optional SSR
|
||||
- 🎨 **Modern**: Component-based with Tailwind
|
||||
- 📦 **Portable**: Can integrate React, Vue, Svelte if needed
|
||||
- 🔍 **SEO**: Great for content-driven sites
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### API can't connect to Directus
|
||||
|
||||
```bash
|
||||
# Check Directus is running
|
||||
curl ${DIRECTUS_URL}/server/health
|
||||
|
||||
# Check API logs
|
||||
docker compose logs api
|
||||
|
||||
# Verify environment variable
|
||||
docker compose exec api env | grep DIRECTUS_URL
|
||||
```
|
||||
|
||||
### Frontend won't load
|
||||
|
||||
```bash
|
||||
# Check API is responding
|
||||
curl http://localhost:3000/health
|
||||
|
||||
# Check frontend logs
|
||||
docker compose logs frontend
|
||||
|
||||
# Rebuild frontend
|
||||
docker compose up -d --build frontend
|
||||
```
|
||||
|
||||
### Content not showing
|
||||
|
||||
1. Verify Directus has data in collections
|
||||
2. Check API endpoints directly: `curl http://localhost:3000/api/posts`
|
||||
3. Check browser console for errors
|
||||
|
||||
## Related Repositories
|
||||
|
||||
- [portfolio-infrastructure](../../infrastructure/directus) - Shared Directus CMS
|
||||
|
||||
## Built By
|
||||
|
||||
John Chen - [Portfolio](https://b28.dev) - [GitHub](https://git.b28.dev)
|
||||
|
||||
## License
|
||||
|
||||
This demo is for portfolio purposes. Source code is available for reference.
|
||||
Reference in New Issue
Block a user