Skip to content
IONFLOW Docs

Installation

Installation

Section titled “Installation”

This guide walks you through the complete installation process for IONFLOW Frontend.

System Requirements

Section titled “System Requirements”

Minimum Requirements

Section titled “Minimum Requirements”
ComponentRequirement
OSmacOS, Linux, or Windows (WSL2 recommended)
CPU2+ cores
RAM8GB+
Disk5GB free space

Software Requirements

Section titled “Software Requirements”
SoftwareVersionInstallation
Node.js18.x or 20.xnodejs.org or fnm
pnpm8.x+npm install -g pnpm
GitLatestgit-scm.com

Installation Steps

Section titled “Installation Steps”

1. Install Node.js

Section titled “1. Install Node.js”

Using fnm (recommended):

Terminal window
# Install fnm
curl -fsSL https://fnm.vercel.app/install | bash


# Install Node.js
fnm install 20
fnm use 20


# Verify installation
node --version  # Should show v20.x.x

2. Install pnpm

Section titled “2. Install pnpm”
Terminal window
# Install pnpm globally
npm install -g pnpm


# Verify installation
pnpm --version  # Should show 8.x.x or higher

3. Clone the Repository

Section titled “3. Clone the Repository”
Terminal window
# Clone the repository
git clone [email protected]:altacrest/gateway-ion.git


# Navigate to project directory
cd ion

4. Install Dependencies

Section titled “4. Install Dependencies”
Terminal window
# Install all dependencies
pnpm install

This will install:

  • Vue 3 and related packages
  • PrimeVue components
  • Tailwind CSS
  • TypeScript
  • Testing libraries
  • All other dependencies

5. Configure Environment

Section titled “5. Configure Environment”

Copy the example environment file:

Terminal window
cp .env.example .env.local

Edit .env.local with your configuration:

Terminal window
# API Configuration
VITE_API_URL=http://localhost:8000/api
VITE_API_VERSION=v1


# Keycloak Configuration
VITE_KEYCLOAK_URL=http://localhost:8080
VITE_KEYCLOAK_REALM=ionflow
VITE_KEYCLOAK_CLIENT_ID=ionflow-frontend


# Feature Flags
VITE_ENABLE_DEV_TOOLS=true

6. Start Development Server

Section titled “6. Start Development Server”
Terminal window
pnpm dev

The application will be available at http://localhost:5173.

Verifying Installation

Section titled “Verifying Installation”

After starting the development server, verify:

  1. Application loads: Navigate to http://localhost:5173
  2. No console errors: Check browser developer tools
  3. Hot reload works: Make a change and verify it updates

Troubleshooting

Section titled “Troubleshooting”

Common Issues

Section titled “Common Issues”

”Module not found” errors

Section titled “”Module not found” errors”
Terminal window
# Clear node_modules and reinstall
rm -rf node_modules
pnpm install

Port already in use

Section titled “Port already in use”
Terminal window
# Use a different port
pnpm dev --port 3000

Node version mismatch

Section titled “Node version mismatch”
Terminal window
# Check required version in package.json
# Then switch to correct version
fnm use 20

pnpm lockfile issues

Section titled “pnpm lockfile issues”
Terminal window
# Regenerate lockfile
rm pnpm-lock.yaml
pnpm install

Platform-Specific Issues

Section titled “Platform-Specific Issues”

Windows

Section titled “Windows”
  • Use WSL2 for better compatibility
  • Enable long paths: git config --global core.longpaths true

macOS

Section titled “macOS”
  • If using M1/M2, ensure Rosetta 2 is installed for compatibility

Linux

Section titled “Linux”
  • Ensure build-essential is installed for native modules

Optional Setup

Section titled “Optional Setup”

Docker Development (Alternative)

Section titled “Docker Development (Alternative)”
Terminal window
# Build and run with Docker
docker-compose up -d

Database Setup (if needed)

Section titled “Database Setup (if needed)”

The frontend connects to backend APIs. Ensure the backend services are running:

Terminal window
# Check backend health
curl http://localhost:8000/health

Next Steps

Section titled “Next Steps”
Section titled “Related”