How to Deploy & Use akveo/ng2-admin

# ngx-admin Deployment & Usage Guide

A comprehensive guide for deploying and customizing the ngx-admin Angular dashboard template.

## Prerequisites

- **Node.js**: Version 14.14 or higher (required for node-sass compatibility)
- **Package Manager**: npm (v6+) or Yarn
- **Git**: For cloning the repository
- **Angular CLI** (optional): `npm install -g @angular/cli` for CLI commands
- **Modern Browser**: Chrome, Firefox, Safari, or Edge (latest versions)

## Installation

### 1. Clone the Repository

```bash
git clone https://github.com/akveo/ngx-admin.git
cd ngx-admin

For the Material Design theme:

git checkout feat/material-theme

2. Verify Node Version

node --version  # Must be v14.14.0 or higher

If using nvm:

nvm install 14.14.0
nvm use 14.14.0

3. Install Dependencies

npm install

Or with Yarn:

yarn install

Configuration

Environment Variables

Edit environment files in src/environments/:

Development (environment.ts):

export const environment = {
  production: false,
  apiUrl: 'http://localhost:3000/api',
  // Add custom config here
};

Production (environment.prod.ts):

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

Theme Configuration

Themes are located in src/app/@theme/styles/. Available themes:

theme.default.ts - Default light theme
theme.dark.ts - Dark theme
theme.cosmic.ts - Cosmic purple theme
theme.corporate.ts - Corporate blue theme

To customize colors, edit the theme file:

export const COSMIC_THEME = {
  name: 'cosmic',
  base: 'cosmic',
  variables: {
    primary: '#3366ff',
    // Modify chart colors, backgrounds, etc.
    temperature: {
      arcFill: ['#2ec7fe', '#31ffad', '#7bff24'],
    }
  }
};

Map Assets (for Bubble Maps)

Ensure map data is available at src/assets/map/world.json for the bubble map component. If missing, download from ECharts map collection and place in the assets folder.

Build & Run

Development Server

ng serve
# or
npm start

Navigate to http://localhost:4200/. The app will auto-reload on file changes.

Production Build

ng build --configuration production

Output will be in dist/ directory. For older Angular CLI versions:

ng build --prod

Build with Specific Base Href

For deployment to subdirectory:

ng build --configuration production --base-href /admin/

Deployment

Static Hosting (Recommended)

Netlify:

ng build --configuration production
netlify deploy --prod --dir=dist/ngx-admin

Vercel:

vercel --prod

Firebase Hosting:

firebase init hosting
ng build --configuration production
firebase deploy

Docker Deployment

Create Dockerfile:

FROM node:14-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build -- --configuration production

FROM nginx:alpine
COPY --from=build /app/dist/ngx-admin /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf

Create nginx.conf for SPA routing:

server {
    listen 80;
    location / {
        root /usr/share/nginx/html;
        index index.html index.htm;
        try_files $uri $uri/ /index.html =404;
    }
}

Build and run:

docker build -t ngx-admin .
docker run -p 80:80 ngx-admin

AWS S3 + CloudFront

ng build --configuration production
aws s3 sync dist/ngx-admin s3://your-bucket-name --delete
aws cloudfront create-invalidation --distribution-id YOUR_ID --paths "/*"

Troubleshooting

Node-sass Compilation Errors

Issue: Error: Node Sass does not yet support your current environment

Solution: Ensure Node.js version is 14.14+:

node --version
# If incorrect, switch versions
nvm use 14.14.0
rm -rf node_modules package-lock.json
npm install

Memory Issues During Build

Issue: JavaScript heap out of memory

Solution: Increase Node memory limit:

node --max_old_space_size=4096 ./node_modules/@angular/cli/bin/ng build --configuration production

Or on Windows:

set NODE_OPTIONS=--max_old_space_size=4096
ng build --configuration production

Theme Not Applying

Issue: Custom theme colors not reflecting

Solution:

Check theme registration in src/app/@theme/styles/themes.scss
Verify theme name matches in theme.<name>.ts
Clear browser cache and reload

Map Data Not Loading (Bubble Maps)

Issue: World map shows blank or error in console

Solution: Verify src/assets/map/world.json exists. If missing:

mkdir -p src/assets/map
curl -o src/assets/map/world.json https://raw.githubusercontent.com/apache/echarts/master/test/data/map/json/world.json

CORS Issues with API

Issue: API calls blocked by CORS policy

Solution: Configure proxy for development in proxy.conf.json:

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

Then run: ng serve --proxy-config proxy.conf.json

Maintenance Mode Notice

Note: This repository is currently in minimal maintenance mode. The maintainers focus primarily on Angular version updates. For production use, fork the repository to maintain your own updates and security patches.