Deployment Guide

Quick Reference

• Platform: Docker (Node 20 + Nginx Alpine)
• Port: 80 (Nginx)
• CI/CD: GitHub Actions (build + test)
• Package Manager: Bun (dev) / npm (CI)
• Build Output: dist/boxme-insight/browser

System Requirements

Component	Minimum	Recommended
Node.js	18.x	20.x
npm	9.x	10.x
Bun (optional)	1.0+	Latest
RAM (build)	2 GB	4 GB
Disk	500 MB	1 GB

Environment Variables

Variable	Mô tả	Required	Default
production	Chế độ production	Yes	false
demoMode	Bật mock data (không gọi API)	No	true (dev), false (prod)
apiBaseUrl	URL backend API	Yes	https://insights.omisell.com
globalLoginUrl	URL trang login parent app	Yes	https://oms.boxme.asia/login
globalLogoutUrl	URL trang logout	Yes	https://oms.boxme.asia/logout
tokenStorageKey	Key lưu token trong localStorage	No	boxme_insight_token

Source: (src/environments/environment.ts:1-8), (src/environments/environment.prod.ts:1-8)

WARNING

Đảm bảo demoMode = false trong production. Demo mode sẽ trả mock data thay vì gọi API thật.

Local Development Setup

npm

# Clone repository
git clone <repo-url>
cd boxme-insight

# Install dependencies
npm install

# Start dev server (port 4200)
npm start
# → http://localhost:4200

bun

# Install dependencies (faster)
bun install

# Start dev server
bun run start
# → http://localhost:4200

TIP

Dev server chạy ở demoMode=true mặc định — không cần backend. Để test với backend thật, sửa src/environments/environment.ts: demoMode: false.

Build Production

# Build production bundle
npm run build -- --configuration=production

# Output directory
ls dist/boxme-insight/browser/

Build output là static files (HTML/CSS/JS), serve bằng bất kỳ web server nào.

Docker Deployment

Dockerfile (Multi-stage Build)

# Stage 1: Build Angular app
FROM node:20-alpine as build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build --configuration=production

# Stage 2: Serve with Nginx
FROM nginx:alpine
COPY --from=build /app/dist/boxme-insight/browser /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

Source: (Dockerfile:1-26)

Build & Run

# Build Docker image
docker build -t boxme-insight .

# Run container
docker run -d -p 8080:80 --name boxme-insight boxme-insight

# Verify
curl http://localhost:8080

Nginx Configuration (Optional)

Nếu cần custom Nginx config (SPA routing, gzip, headers):

server {
    listen 80;
    server_name _;
    root /usr/share/nginx/html;
    index index.html;

    # SPA fallback — Angular routes
    location / {
        try_files $uri $uri/ /index.html;
    }

    # Gzip compression
    gzip on;
    gzip_types text/plain text/css application/json application/javascript;

    # Cache static assets
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

CI/CD Pipeline

GitHub Actions

Source: (.github/workflows/ci.yml:1-34)

Trigger	Branches
Push	main, develop
Pull Request	main, develop

Step	Command	Mô tả
Checkout	actions/checkout@v4	Clone repo
Setup Node	actions/setup-node@v4	Node 20.x + npm cache
Install	npm ci	Install exact versions
Build	npm run build	Production build
Test	npm test -- --watch=false	Run Vitest

Testing

# Run unit tests (Vitest)
npm test

# Run tests once (CI mode)
npm test -- --watch=false

Monitoring & Health

Endpoint	Mô tả	Expected
http://host:80/	App entry point	200 OK + HTML
http://host:80/assets/	Static assets	200 OK

INFO

App hiện chưa có dedicated health check endpoint. Nginx sẽ trả 200 cho / nếu static files được serve đúng.

Liên kết

• Architecture — Kiến trúc hệ thống
• Data Flow — Luồng dữ liệu
• SOP Frontend Development — Quy trình phát triển