Merge pull request #17 from Boxuan-Matty-Lin/feat/mvp-dockerfile-setting

Finish updating README for the project, finish setting docker for the project

Author: Boxuan-Matty-Lin

.dockerignore

@@ -0,0 +1,27 @@
+# Git / VCS
+.git
+.gitignore
+
+# Node dependencies & caches
+node_modules
+.pnpm-store
+.npm
+.cache
+.next/cache
+
+# Build outputs & coverage
+.next
+dist
+coverage
+
+# Logs & editor settings
+*.log
+logs
+*.swp
+*.swo
+.vscode
+.idea
+
+# Env files (改为在运行容器时注入)
+.env
+.env.*

Dockerfile

@@ -0,0 +1,55 @@
+# ===== 0) Dev stage =====
+FROM node:22-alpine AS dev
+WORKDIR /app
+# Install base tools and pin pnpm via Corepack
+RUN apk add --no-cache libc6-compat ca-certificates \
+ && corepack enable && corepack prepare pnpm@9.12.0 --activate
+# Pre-install dependencies to speed up first run (source code will be bind-mounted in compose)
+COPY package.json pnpm-lock.yaml ./
+RUN pnpm install --frozen-lockfile
+# Expose dev server port and run Next.js in dev mode (HMR enabled)
+EXPOSE 3000
+CMD ["pnpm", "dev"]
+
+
+# ===== 1) Build stage =====
+FROM node:22-alpine AS builder
+WORKDIR /app
+
+# Install musl compatibility libs for common native deps (e.g., sharp)
+RUN apk add --no-cache libc6-compat
+
+# Pin pnpm via corepack to avoid version drift
+RUN corepack enable && corepack prepare pnpm@9.12.0 --activate
+
+# Install dependencies
+COPY package.json pnpm-lock.yaml ./
+RUN pnpm install --frozen-lockfile
+
+# Copy source code and build
+COPY . .
+# Important: ensure next.config.js has { output: 'standalone' }
+ENV NODE_ENV=production
+RUN pnpm build
+
+# ===== 2) Runtime stage =====
+FROM node:22-alpine AS runner
+WORKDIR /app
+RUN apk add --no-cache libc6-compat
+
+ENV NODE_ENV=production
+ENV NEXT_TELEMETRY_DISABLED=1
+ENV HOSTNAME=0.0.0.0
+ENV PORT=3000
+
+# Run as non-root user
+RUN addgroup -g 1001 nodejs && adduser -S nextjs -u 1001
+USER nextjs
+
+# Copy only the runtime artifacts
+COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
+COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
+COPY --from=builder --chown=nextjs:nodejs /app/public ./public
+
+EXPOSE 3000
+CMD ["node", "server.js"]

README.md

@@ -1,36 +1,98 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+# Currency Converter
 
-## Getting Started
+## Project Overview
+This is a currency conversion web application that allows users to input an amount in Australian dollars (AUD) and instantly convert it into five target currencies: USD, EUR, JPY, GBP, and CNY. The interface also provides a 14-day time series chart that visualizes historical exchange rates for the selected currency pair.
 
-First, run the development server:
+**Tech Stack:** ui:next.js 16 + react 19 + tailwindcss 4 + lucide / data:open exchange rates API / charts:recharts / testing:vitest + testing-library + happy-dom / tooling:pnpm + TypeScript + eslint
 
-```bash
-npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
-```
 
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+## Quick Start (Local Development)
+
+1. **Clone the repository**
+   ```bash
+   git clone <repository-url>
+   cd currency_converter
+   ```
+
+2. **Install dependencies**
+   ```bash
+   pnpm install
+   ```
+
+3. **Configure environment variables**
+   Create a file named `.env.development` in the project root and specify required credentials. Example:
+   ```dotenv
+   OXR_BASE_URL=https://openexchangerates.org/api
+   OXR_APP_ID=your-openexchangerates-app-id
+   ```
 
-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+4. **Run the development server**
+   ```bash
+   pnpm dev
+   ```
 
-This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+5. **Access the app**
+   Navigate to [http://localhost:3000](http://localhost:3000). Hot module replacement is enabled, so the UI updates automatically when you edit files.
 
-## Learn More
+## Running via Docker (Development)
 
-To learn more about Next.js, take a look at the following resources:
+1. Ensure Docker is running on your machine.
+2. Copy `.env.development` (with the required `OXR_BASE_URL` and `OXR_APP_ID`) into the project root.
+3. Build and start the dev container using the provided compose file:
+   ```bash
+   docker compose -f compose.dev.yml up --build
+   ```
+4. Your app will be available at [http://localhost:3000](http://localhost:3000), and code changes on the host filesystem will be hot-reloaded inside the container.
+5. To stop the container, press `Ctrl+C` or run `docker compose -f compose.dev.yml down`.
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+## Deploying with Docker Compose (Production)
+
+1. Prepare a production env file (e.g. `.env.production`) with the required secrets:
+   ```dotenv
+   OXR_BASE_URL=https://openexchangerates.org/api
+   OXR_APP_ID=your-openexchangerates-app-id
+   ```
+2. Build and start the runtime container using the production compose file:
+   ```bash
+   docker compose -f compose.production.yml up --build -d
+   ```
+   This will build the multi-stage Dockerfile and run the `runner` stage, exposing port 3000.
+3. Verify the app at [http://localhost:3000](http://localhost:3000) or on your chosen host.
+4. To inspect logs:
+   ```bash
+   docker compose -f compose.production.yml logs -f
+   ```
+5. To stop the service:
+   ```bash
+   docker compose -f compose.production.yml down
+   ```
+
+## Testing
+
+Before running integration tests locally, create a `.env.test` file in the project root with your Open Exchange Rates credentials:
+```dotenv
+OXR_BASE_URL=https://openexchangerates.org/api
+OXR_APP_ID=your-openexchangerates-app-id
+```
 
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+1. **Run all tests (unit + integration)**  
+   ```bash
+   pnpm test
+   ```
 
-## Deploy on Vercel
+2. **Unit tests only** (fast feedback, no external calls)  
+   ```bash
+   pnpm test:unit
+   ```
 
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+3. **Integration tests only** (hits real OXR API)  
+   ```bash
+   pnpm test:integration
+   ```
+   Requires the `.env.test` file (or equivalent environment variables) described above.
 
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+4. **Continuous integration run with coverage**  
+   ```bash
+   pnpm test:ci
+   ```
+   Generates coverage reports under `coverage/`.

compose.dev.yml

@@ -0,0 +1,17 @@
+services:
+  web:
+    build:
+      context: .
+      target: dev        
+    command: pnpm dev
+    ports: ["3000:3000"]
+    env_file:
+      - .env.development
+    environment:
+      NODE_ENV: development
+      CHOKIDAR_USEPOLLING: "1"   
+    volumes:
+      - .:/app
+      - node-mod:/app/node_modules
+volumes:
+  node-mod:

compose.production.yml

@@ -0,0 +1,16 @@
+services:
+  web:
+    build:
+      context: .
+      target: runner              # build the minimal runtime image
+    env_file:
+      - .env.production           # runtime-only envs for the server
+    environment:
+      NODE_ENV: production
+      NEXT_TELEMETRY_DISABLED: "1"
+      HOSTNAME: 0.0.0.0
+      PORT: "3000"
+    ports:
+      - "3000:3000"
+    restart: unless-stopped
+  

next.config.ts

@@ -2,6 +2,7 @@ import type { NextConfig } from "next";
 
 const nextConfig: NextConfig = {
   /* config options here */
+  output: "standalone",
 };
 
 export default nextConfig;