jcoliz/yofi-v3-frontend repository overview

⁠YoFi.V3 Frontend Docker Image

Docker container image for the YoFi.V3 frontend application, a modern Vue.js/Nuxt web interface for personal finance management.

⁠What is YoFi.V3?

YoFi.V3 is a web-based personal finance application that helps you track and manage your financial transactions. The frontend provides:

• Modern Web Interface - Responsive, user-friendly interface built with Vue 3 and Nuxt 4
• Transaction Management - Intuitive forms and views for managing financial data
• User Authentication - Registration, login, and secure session management
• Real-time Updates - Dynamic interface with seamless API integration
• Bootstrap Design - Professional, mobile-responsive design system
• TypeScript Safety - Type-safe code for better reliability

This container provides the frontend web application. It connects to a separate backend API service for data and business logic.

Technology Stack:

• Nuxt 4 (Vue.js meta-framework)
• Vue 3 with TypeScript
• Bootstrap 5 for styling
• Pinia for state management
• Nginx for static file serving

⁠Quick Start

Pull and run the frontend container:

docker run -p 5000:80 yofi-v3-frontend

The application will be available at http://localhost:5000⁠

⚠️ Note: The frontend requires a running backend API. Configure the API URL using build arguments (see Configuration section).

⁠Image Details

A static site generated by Nuxt and served by Nginx.

Features:

• Server-side rendered (SSR) Vue.js application built as static site
• Nginx-based web server for optimal performance
• Bootstrap 5 responsive design
• JWT-based authentication flows
• TypeScript for type safety
• Application Insights integration (optional)

Base Image: nginx:alpine

Exposed Ports:

• 80 - HTTP web server

⁠Building from Source

⁠Prerequisites

• Docker Desktop or Docker Engine
• Source code from YoFi.V3 repository⁠

⁠Build the Image

From the frontend directory (src/FrontEnd.Nuxt):

docker build -f docker/Dockerfile \
  --build-arg NUXT_PUBLIC_API_BASE_URL=http://localhost:5001 \
  -t yofi-v3-frontend .

Or use the convenience script from repository root:

.\scripts\Build-Container.ps1

⁠Build Arguments

Configure the application at build time using these arguments:

⚠️ Important: The API base URL is baked into the static site at build time. You must rebuild the image if the backend URL changes.

Example with all arguments:

docker build -f docker/Dockerfile \
  --build-arg NUXT_PUBLIC_API_BASE_URL=https://api.example.com \
  --build-arg NUXT_PUBLIC_SOLUTION_VERSION=1.0.0 \
  --build-arg NUXT_PUBLIC_APPLICATION_INSIGHTS_CONNECTION_STRING="InstrumentationKey=abc123" \
  -t yofi-v3-frontend:1.0.0 .

⁠Configuration

⁠Static Build Configuration

Since this is a static site, all configuration is set at build time via build arguments. Runtime environment variables have no effect on the application behavior.

⁠Backend API Connection

The frontend connects to the backend API using the URL specified in NUXT_PUBLIC_API_BASE_URL. This URL must be:

• Accessible from the user's browser (not from inside the container)
• The same origin or properly configured for CORS
• Running the YoFi.V3 backend API

Common configurations:

Local development:

--build-arg NUXT_PUBLIC_API_BASE_URL=http://localhost:5001

Production with backend on Azure:

--build-arg NUXT_PUBLIC_API_BASE_URL=https://your-backend.azurewebsites.net

Docker Compose (both containers):

--build-arg NUXT_PUBLIC_API_BASE_URL=http://localhost:5001

⁠Custom Nginx Configuration

The image includes a custom Nginx configuration at docker/nginx.conf⁠. Modify this file to customize:

• Request routing
• Compression settings
• Cache headers
• Security headers

⁠Usage

⁠Run the Container

Start in foreground with logs:

docker run -p 5000:80 yofi-v3-frontend

Start in background (detached):

docker run -d -p 5000:80 --name yofi-frontend yofi-v3-frontend

⁠Custom Port Mapping

Run on a different port:

docker run -p 8080:80 yofi-v3-frontend
# Access at http://localhost:8080

⁠View Logs

docker logs -f yofi-frontend

⁠Stop the Container

docker stop yofi-frontend
docker rm yofi-frontend

⁠Application Routes

Once running, access these pages:

• Home: http://localhost:5000/⁠
• Login: http://localhost:5000/login⁠
• Register: http://localhost:5000/register⁠
• Profile: http://localhost:5000/profile⁠ (requires login)
• Weather: http://localhost:5000/weather⁠ (sample page)
• Health: http://localhost:5000/health⁠

⁠Connecting to Backend

The frontend expects the backend API to be available at the URL specified during build.

⁠Local Development Setup

1. Start the backend container:

   docker run -p 5001:8080 \
     -e APPLICATION__ALLOWEDCORSORIGINS__0=http://localhost:5000 \
     --env-file .env \
     yofi-v3-backend
   

   Copy

2. Build frontend with backend URL:

   docker build -f docker/Dockerfile \
     --build-arg NUXT_PUBLIC_API_BASE_URL=http://localhost:5001 \
     -t yofi-v3-frontend .
   

   Copy

3. Start the frontend:

   docker run -p 5000:80 yofi-v3-frontend
   

   Copy

⁠Using Docker Compose

The repository includes a docker-compose-ci.yml⁠ that orchestrates both frontend and backend:

docker compose -f docker/docker-compose-ci.yml up

⁠Troubleshooting

⁠Cannot Connect to Backend

Symptom: Network errors or "Cannot connect to API" messages

Solutions:

1. Verify backend is running: curl http://localhost:5001/health
2. Check API URL was set correctly during build
3. Verify CORS is configured on backend for frontend origin
4. Check browser console for detailed error messages

⁠404 Errors on Page Refresh

Symptom: Direct navigation to routes (other than /) returns 404

Solution: This is handled by the Nginx configuration. Verify nginx.conf⁠ includes:

try_files $uri $uri/ /index.html;

⁠Authentication Not Working

Symptom: Login succeeds but redirects fail or session is lost

Solutions:

1. Check JWT configuration matches between frontend and backend
2. Verify backend JWT issuer/audience URLs
3. Check browser console for auth errors
4. Verify cookies/localStorage are not blocked

⁠Stale Application After Rebuild

Symptom: Changes don't appear after rebuilding

Solutions:

1. Clear browser cache (hard refresh: Ctrl+F5 or Cmd+Shift+R)
2. Remove old container and image:

   docker rm -f yofi-frontend
   docker rmi yofi-v3-frontend
   

   Copy
3. Rebuild with --no-cache:

   docker build --no-cache -f docker/Dockerfile ...
   

   Copy

⁠Performance

Build Times:

• First build: ~2-3 minutes
• Incremental builds: ~1-2 minutes (with layer caching)

Resource Usage:

• Memory: ~20 MB RAM (Nginx)
• Storage: ~100 MB disk space

Optimization: The image uses multi-stage builds to minimize final image size. Only the compiled static files and Nginx are included in the production image.

⁠Development vs Production

This container is designed for production-like deployments. For local development:

Recommended for development:

cd src/FrontEnd.Nuxt
npm install
npm run dev

Use containers for:

• Testing production builds
• Running functional tests
• Demonstrating to stakeholders
• CI/CD pipelines

⁠Testing

Run functional tests against the containerized application:

.\scripts\Run-FunctionalTestsVsContainer.ps1

This script:

1. Builds both frontend and backend containers
2. Starts them with test configuration
3. Runs the complete Playwright test suite
4. Tears down the environment

⁠Related Documentation

• Container Environment Guide⁠ - Detailed containerization documentation
• Deployment Guide⁠ - Production deployment to Azure
• Architecture Overview⁠ - Application architecture
• Contributing Guide⁠ - Development setup and guidelines
• Backend Container README⁠ - Backend API container documentation

⁠Security Considerations

• Static files are served by Nginx (no server-side code execution)
• API authentication handled via JWT tokens
• Secrets (JWT keys) stored in backend, not frontend
• Enable HTTPS in production (configure at reverse proxy or CDN)
• Set appropriate security headers in Nginx configuration
• Regularly update base images for security patches

⁠Support

For issues, questions, or contributions:

• GitHub Repository: https://github.com/jcoliz/YoFi.V3⁠
• Issues: https://github.com/jcoliz/YoFi.V3/issues⁠

⁠License

This project is open source. See the LICENSE file in the repository for details.