Installation

This guide covers all installation methods for the Biblioteca Virtual Frontend, from local development to Docker deployment and CI/CD setup.

Prerequisites

For Local Development

Node.js 20+

Required for running Angular CLI and building the application

npm

Package manager (included with Node.js)

Git

Version control to clone the repository

Angular CLI

Optional but recommended for development

For Docker Deployment

Docker 20.10+ or higher
Docker Compose (optional, for orchestration)

With Docker, you don’t need Node.js or Angular CLI installed locally. Everything runs in containers.

Installation Methods

Local Development
Docker
Docker Hub

Local Development Setup

This method is ideal for active development work with hot reload and debugging tools.

Clone the repository

git clone https://github.com/AngheloMP10/biblioteca-virtual-frontend.git
cd biblioteca-virtual-frontend

Install dependencies

npm install

This installs all packages from package.json:Core Dependencies:

{
  "@angular/common": "^20.0.0",
  "@angular/compiler": "^20.0.0",
  "@angular/core": "^20.0.0",
  "@angular/forms": "^20.0.0",
  "@angular/platform-browser": "^20.0.0",
  "@angular/router": "^20.0.0",
  "rxjs": "~7.8.0",
  "tslib": "^2.3.0",
  "zone.js": "~0.15.0"
}

Configure environment

Set up your environment configuration in src/environments/environment.ts:

src/environments/environment.ts

export const environment = {
  production: false,
  apiUrl: 'http://localhost:8080', // Your backend API URL
};

For production builds, configure src/environments/environment.prod.ts:

src/environments/environment.prod.ts

export const environment = {
  production: true,
  apiUrl: 'https://your-api-domain.com',
};

Start development server

npm start

The application will be available at http://localhost:4200

Docker Installation

Deploy the application in a containerized environment with Nginx.

Clone the repository

git clone https://github.com/AngheloMP10/biblioteca-virtual-frontend.git
cd biblioteca-virtual-frontend

Review Dockerfile

The project includes a multi-stage Dockerfile for optimized builds:

Dockerfile

# ===== STAGE 1: Build Angular =====
FROM node:20-alpine AS build

WORKDIR /app

COPY package*.json ./
RUN npm install

COPY . .
RUN npm run build -- --configuration production


# ===== STAGE 2: Nginx =====
FROM nginx:alpine

# Remove default config
RUN rm /etc/nginx/conf.d/default.conf

# Copy our configuration
COPY nginx.conf /etc/nginx/conf.d

# Copy Angular build to web server
COPY --from=build /app/dist/biblioteca-front/browser /usr/share/nginx/html

EXPOSE 80

CMD ["nginx", "-g", "daemon off;"]

This multi-stage build keeps the final image small by only including the built artifacts and Nginx, not the entire Node.js build environment.

Review Nginx configuration

The nginx.conf file configures the web server:

nginx.conf

server {
    listen 80;
    server_name localhost;

    location / {
        root   /usr/share/nginx/html;
        index  index.html;
        try_files $uri $uri/ /index.html;
    }
}

The try_files directive ensures Angular’s client-side routing works correctly by serving index.html for all routes.

Build Docker image

docker build -t biblioteca-virtual-frontend .

Expected output:

[+] Building 125.4s (15/15) FINISHED
 => [internal] load build definition from Dockerfile
 => [internal] load .dockerignore
 => [build 1/6] FROM docker.io/library/node:20-alpine
 => [build 2/6] WORKDIR /app
 => [build 3/6] COPY package*.json ./
 => [build 4/6] RUN npm install
 => [build 5/6] COPY . .
 => [build 6/6] RUN npm run build -- --configuration production
 => [stage-1 2/4] RUN rm /etc/nginx/conf.d/default.conf
 => [stage-1 3/4] COPY nginx.conf /etc/nginx/conf.d
 => [stage-1 4/4] COPY --from=build /app/dist/biblioteca-front/browser
 => exporting to image
 => => naming to docker.io/library/biblioteca-virtual-frontend

Run the container

docker run -d -p 80:80 --name biblioteca-frontend biblioteca-virtual-frontend

Access the application at http://localhostCommon Docker commands:

# Stop the container
docker stop biblioteca-frontend

# Start the container
docker start biblioteca-frontend

# View logs
docker logs biblioteca-frontend

# Remove the container
docker rm biblioteca-frontend

Pull from Docker Hub

If the image is already published to Docker Hub, you can pull and run it directly.

Pull the image

docker pull <dockerhub-username>/biblioteca-virtual-frontend:latest

Run the container

docker run -d -p 80:80 --name biblioteca-frontend \
  <dockerhub-username>/biblioteca-virtual-frontend:latest

The application will be available at http://localhost

Replace <dockerhub-username> with the actual Docker Hub username where the image is published.

Build Configurations

The project includes multiple build configurations defined in angular.json:

Development Build

npm run watch

Features:

Source maps enabled
No optimization
No license extraction
Fast rebuild times

Production Build

npm run build

Features:

Full optimization
Output hashing for cache busting
Bundle budgets:
- Initial bundle: 500kB warning, 1MB error
- Component styles: 4kB warning, 8kB error

Output location: dist/biblioteca-front/browser/

Netlify Build

npm run build:netlify

Features:

Uses environment.netlify.ts configuration
Output hashing enabled
Optimized for Netlify deployment

The Netlify build uses environment file replacement to inject production API URLs.

TypeScript Configuration

The project uses strict TypeScript configuration for type safety:

tsconfig.json

{
  "compilerOptions": {
    "strict": true,
    "noImplicitOverride": true,
    "noPropertyAccessFromIndexSignature": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "skipLibCheck": true,
    "isolatedModules": true,
    "experimentalDecorators": true,
    "target": "ES2022",
    "module": "preserve"
  },
  "angularCompilerOptions": {
    "strictInjectionParameters": true,
    "strictInputAccessModifiers": true,
    "strictTemplates": true
  }
}

CI/CD Setup

The project includes GitHub Actions workflow for automated Docker builds and deployment.

GitHub Actions Workflow

.github/workflows/docker-frontend.yml

name: Frontend CI/CD - Docker Hub

on:
  push:
    branches: ["main"]

jobs:
  build-and-push:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Build Docker image
        run: docker build -t ${{ secrets.DOCKERHUB_USERNAME }}/biblioteca-virtual-frontend:latest .

      - name: Push Docker image
        run: docker push ${{ secrets.DOCKERHUB_USERNAME }}/biblioteca-virtual-frontend:latest

Setting up CI/CD

Add Docker Hub credentials

In your GitHub repository settings, add these secrets:

DOCKERHUB_USERNAME: Your Docker Hub username
DOCKERHUB_TOKEN: Your Docker Hub access token

Enable GitHub Actions

Ensure GitHub Actions is enabled in your repository settings

Push to main branch

Every push to the main branch will trigger:

Docker image build
Push to Docker Hub
Image tagged as latest

You can monitor the build status in the “Actions” tab of your GitHub repository.

Project Structure

After installation, your project structure will look like this:

biblioteca-virtual-frontend/
├── src/
│   ├── app/
│   │   ├── auth/              # Authentication components
│   │   ├── core/              # Core services, guards, interceptors
│   │   │   ├── guards/        # Route guards (auth, admin, public)
│   │   │   ├── interceptors/  # HTTP interceptors
│   │   │   ├── models/        # TypeScript interfaces
│   │   │   └── services/      # API services
│   │   ├── features/          # Feature modules
│   │   │   ├── autores/       # Authors management
│   │   │   ├── catalogo/      # Book catalog
│   │   │   ├── generos/       # Genres management
│   │   │   ├── libros/        # Books management
│   │   │   └── prestamos/     # Loans management
│   │   ├── shared/            # Shared components
│   │   ├── app.config.ts      # Application configuration
│   │   ├── app.routes.ts      # Route definitions
│   │   └── app.ts             # Root component
│   ├── environments/          # Environment configurations
│   ├── assets/                # Static assets
│   ├── styles.css             # Global styles
│   └── main.ts                # Application entry point
├── angular.json               # Angular workspace configuration
├── package.json               # Dependencies and scripts
├── tsconfig.json              # TypeScript configuration
├── Dockerfile                 # Docker build instructions
├── nginx.conf                 # Nginx web server configuration
└── README.md                  # Project documentation

Next Steps

Quickstart Guide

Get up and running in 5 minutes

Configuration

Learn about environment variables and configuration options

Architecture

Understand the project architecture

Authentication

Connect to the backend API

Troubleshooting

Docker build fails

Common causes:

Insufficient memory: Increase Docker’s memory allocation
Network issues: Check your internet connection
Disk space: Ensure you have at least 2GB free

Solution:

# Clean Docker cache
docker system prune -a

# Rebuild with verbose output
docker build -t biblioteca-virtual-frontend . --no-cache

npm install fails with permission errors

Solution:Don’t use sudo with npm. Instead, configure npm to use a different directory:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.profile
source ~/.profile

Build exceeds bundle size budgets

If production builds fail due to bundle size:

Error: bundle initial exceeded maximum budget.

Solutions:

Lazy load modules - Split large features into lazy-loaded routes
Optimize imports - Import only what you need from libraries
Increase budgets - Update limits in angular.json (not recommended)

angular.json

"budgets": [
  {
    "type": "initial",
    "maximumWarning": "500kB",
    "maximumError": "1MB"
  }
]

CORS errors when connecting to API

Symptoms:

Access to XMLHttpRequest has been blocked by CORS policy

Solutions:

Configure CORS in your backend to allow http://localhost:4200
Use a proxy configuration in angular.json
Deploy frontend and backend on the same domain

Create proxy.conf.json:

{
  "/api": {
    "target": "http://localhost:8080",
    "secure": false,
    "changeOrigin": true
  }
}

Update package.json:

"start": "ng serve --proxy-config proxy.conf.json"

Getting Started

Core Concepts

Features

Deployment

Prerequisites

For Local Development

Node.js 20+

npm

Git

Angular CLI

For Docker Deployment

Installation Methods

Local Development Setup

Docker Installation

Pull from Docker Hub

Build Configurations

Development Build

Production Build

Netlify Build

TypeScript Configuration

CI/CD Setup

GitHub Actions Workflow

Setting up CI/CD

Project Structure

Next Steps

Quickstart Guide

Configuration

Architecture

Authentication

Troubleshooting

Additional Resources

​Prerequisites

​For Local Development

Node.js 20+

npm

Git

Angular CLI

​For Docker Deployment

​Installation Methods

​Local Development Setup

​Docker Installation

​Pull from Docker Hub

​Build Configurations

​Development Build

​Production Build

​Netlify Build

​TypeScript Configuration

​CI/CD Setup

​GitHub Actions Workflow

​Setting up CI/CD

​Project Structure

​Next Steps

Quickstart Guide

Configuration

Architecture

Authentication

​Troubleshooting

​Additional Resources

Prerequisites

For Local Development

For Docker Deployment

Installation Methods

Local Development Setup

Docker Installation

Pull from Docker Hub

Build Configurations

Development Build

Production Build

Netlify Build

TypeScript Configuration

CI/CD Setup

GitHub Actions Workflow

Setting up CI/CD

Project Structure

Next Steps

Troubleshooting

Additional Resources