tudattr/kilo-cv
1
0
Fork 0
Code Issues Pull Requests 10 Actions Packages Projects Releases 5 Wiki Activity

docs: update all markdown documentation
All checks were successful
Release / Release (push) Successful in 9m39s
Details
Release / Build & Push Docker Image (push) Has been skipped
Details

Browse Source 
- README.md: Update tech stack versions, simplify content, add links to docs
- CONTRIBUTING.md: Add commit guidelines, testing instructions, PR process
- SECURITY.md: Add security measures, vulnerability reporting process
- PULL_REQUEST_TEMPLATE.md: Add conventional commit types, breaking change section
- Remove outdated plan documents (already implemented or superseded)
- architecture.md: Already updated with comprehensive system documentation
- release-engineering.md: Already updated with current pipeline status
This commit is contained in:
Tuan-Dat Tran
2026-02-23 22:53:03 +01:00
parent 8d7000eb31
commit d73e8769c0
8 changed files with 319 additions and 3070 deletions
Download Patch File Download Diff File Expand all files Collapse all files

194
README.md
View File

@@ -1,8 +1,8 @@
# CV - Tuan-Dat Tran
![License](https://img.shields.io/badge/license-MIT-blue.svg)
![React](https://img.shields.io/badge/React-18-61DAFB?logo=react)
![Tailwind CSS](https://img.shields.io/badge/Tailwind-4.1-38B2AC?logo=tailwindcss)
![React](https://img.shields.io/badge/React-19-61DAFB?logo=react)
![Tailwind CSS](https://img.shields.io/badge/Tailwind-4-38B2AC?logo=tailwindcss)
![Vite](https://img.shields.io/badge/Vite-7-646CFF?logo=vite)
A modern, minimalist CV/Resume single-page application with admin panel and persistent storage.
@@ -29,32 +29,33 @@ A modern, minimalist CV/Resume single-page application with admin panel and pers
- Modern, responsive design
- Smooth scroll animations with Framer Motion
- Admin panel for easy CV editing (password protected)
- Admin panel for CV editing (password protected)
- Persistent storage with SQLite
- Docker Compose deployment
- API-based architecture
- RESTful API with OpenAPI documentation
- Optional Keycloak integration for SSO
- Automated releases with semantic-release
## Tech Stack
### Frontend
- **React 18** - UI Library
- **Vite** - Build Tool
- **React 19** - UI Library
- **Vite 7** - Build Tool
- **Tailwind CSS 4** - Styling
- **Framer Motion** - Animations
- **Framer Motion 12** - Animations
- **Lucide React** - Icons
### Backend
- **Express.js** - API Server
- **SQLite** - Database
- **better-sqlite3** - SQLite driver
- **Express.js 4** - API Server
- **Knex.js** - SQL Query Builder
- **SQLite** with **better-sqlite3** - Database
## Getting Started
### Prerequisites
- Node.js 18+
- npm 9+
- Node.js 20+
- npm 10+
- Docker & Docker Compose (optional)
### Option 1: Docker Compose (Recommended)
@@ -66,6 +67,7 @@ docker-compose up -d
# Frontend: http://localhost:5173
# Backend API: http://localhost:3001
# Admin Panel: http://localhost:5173/admin
# API Docs: http://localhost:3001/api/docs
```
### Option 2: Local Development
@@ -86,27 +88,28 @@ npm run dev
### Environment Variables
Frontend (`.env`):
```
VITE_API_URL=http://localhost:3001
```
Backend (`backend/.env`):
```
PORT=3001
DB_PATH=./data/cv.db
USE_KEYCLOAK=false
# Keycloak settings (required if USE_KEYCLOAK=true)
AUTH_MODE=simple
# Keycloak settings (required if AUTH_MODE=keycloak)
KEYCLOAK_URL=https://keycloak.example.com
KEYCLOAK_REALM=your-realm
KEYCLOAK_CLIENT_ID=cv-admin
KEYCLOAK_CLIENT_ID=cv-app
```
## Development Setup
### Pre-commit Setup
This project uses Gitleaks for secret scanning. Install it before committing:
This project uses:
- **ESLint** for code linting
- **commitlint** for commit message validation
- **Husky** for git hooks
- **Gitleaks** for secret scanning
Install Gitleaks before committing:
```bash
# macOS
@@ -120,152 +123,41 @@ sudo mv gitleaks /usr/local/bin/
scoop install gitleaks
```
### API Documentation
### Commit Guidelines
API documentation is available at `/api/docs` when running the server.
Access the interactive Swagger UI at: `http://localhost:3001/api/docs`
## Admin Authentication
### Simple Mode (Default)
- A random password is generated and printed to the console on server startup
- Look for the "ADMIN PASSWORD" banner in the logs
- Enter this password to access the admin panel
### Keycloak Mode
Set `USE_KEYCLOAK=true` and configure Keycloak environment variables:
```bash
USE_KEYCLOAK=true
KEYCLOAK_URL=https://keycloak.example.com
KEYCLOAK_REALM=your-realm
KEYCLOAK_CLIENT_ID=cv-admin
```
## API Endpoints
| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| GET | `/api/cv` | No | Get CV data |
| PUT | `/api/cv` | Yes | Update CV data |
| GET | `/api/cv/export` | No | Export as JSON |
| POST | `/api/cv/import` | Yes | Import JSON data |
| GET | `/api/auth/config` | No | Get auth configuration |
| POST | `/api/auth/login` | No | Login with password |
| GET | `/api/docs` | No | Swagger API documentation |
| GET | `/health` | No | Health check |
## Project Structure
```
.
├── src/ # Frontend source
│ ├── components/ # CV components
│ ├── admin/ # Admin panel
│ ├── lib/ # Utilities
│ └── App.jsx
├── backend/ # Backend source
│ ├── routes/ # API routes
│ ├── db/ # Database
│ └── server.js
├── docker-compose.yml
├── Dockerfile
└── nginx.conf
```
## Testing
```bash
# Frontend tests
npm run test:run
# Backend tests
cd backend && npm test
```
## Release Process
This project uses [semantic-release](https://semantic-release.gitbook.io/) for automated versioning and releases.
### Conventional Commits
All commit messages must follow the [Conventional Commits](https://www.conventionalcommits.org/) specification:
This project uses [Conventional Commits](https://www.conventionalcommits.org/):
```
<type>(<scope>): <description>
[optional body]
[optional footer]
# Examples:
feat(ui): add export button
fix(api): resolve authentication issue
docs(readme): update installation steps
```
#### Commit Types
### API Documentation
| Type | Description | Version Bump |
|------|-------------|--------------|
| `feat` | New feature | Minor |
| `fix` | Bug fix | Patch |
| `feat!` or `BREAKING CHANGE` | Breaking change | Major |
| `docs`, `style`, `refactor`, `test`, `build`, `ci`, `chore` | Non-release changes | None |
Interactive Swagger UI available at: `http://localhost:3001/api/docs`
#### Scopes
## Admin Authentication
Available scopes: `admin`, `api`, `ui`, `docker`, `ci`, `deps`, `release`, `auth`, `skills`, `experience`, `education`, `projects`, `personal`
### Simple Mode (Default)
- Random password generated on server startup
- Password displayed in console logs
- JWT token-based authentication
### Release Workflow
1. Push to `master` branch
2. CI runs tests and linting
3. semantic-release analyzes commits
4. If release needed:
- Version is bumped in package.json
- CHANGELOG.md is updated
- Git tag is created
- GitHub release is published
- Docker images are built and pushed
### Docker Images
Images are published to both Docker Hub and GitHub Container Registry:
| Tag | Description |
|-----|-------------|
| `latest` | Latest stable release |
| `v1.2.3` | Specific version |
| `staging` | Staging environment |
| `nightly`, `edge` | Daily builds from master |
| `YYYY-MM-DD` | Dated nightly build |
```bash
# Pull from Docker Hub
docker pull username/cv-app:latest
# Pull from GHCR
docker pull ghcr.io/owner/cv-app:latest
```
### Environments
| Environment | Branch | Trigger |
|-------------|--------|---------|
| Production | `master` | semantic-release |
| Staging | `staging` | Push to staging |
| Nightly | `master` | Daily at 02:00 UTC |
For detailed documentation, see [Release Engineering Documentation](docs/release-engineering.md).
### Keycloak Mode
- SSO integration via Keycloak
- Configure via `AUTH_MODE=keycloak` and related environment variables
## Documentation
| Document | Description |
|----------|-------------|
| [Release Engineering](docs/release-engineering.md) | Comprehensive release pipeline documentation |
| [Contributing](CONTRIBUTING.md) | Contribution guidelines |
| [Security](SECURITY.md) | Security policy |
## Contributing
Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.
| [Architecture](docs/architecture.md) | System architecture and design patterns |
| [Release Engineering](docs/release-engineering.md) | Release and deployment documentation |
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
MIT License - see [LICENSE](LICENSE) for details.