Huly Platform Deployment & Usage Guide

1. Prerequisites

Before deploying or developing with the Huly Platform, ensure your system meets these requirements:

Runtime & Tools

Node.js: Version 20.11.0 (exact version required)
Docker: For containerized services and dependencies
Docker Compose: For managing multi-container setups
Git: For cloning the repository and submodules

Accounts & Authentication

GitHub Account: Required for accessing GitHub Packages dependencies
GitHub Personal Access Token: With at least read:packages scope for npm authentication

Verification

Confirm your installations with these commands:

node --version  # Should output v20.11.0 or higher
docker --version
docker compose version

2. Installation

Clone the Repository

git clone https://github.com/hcengineering/platform.git
cd platform

Initialize Submodules

The project uses a communication submodule that must be initialized:

git submodule init
git submodule update

Install Rush

Huly uses Microsoft's Rush for monorepo management:

npm install -g @microsoft/rush

Authenticate with GitHub Packages

Since dependencies are hosted on GitHub Packages, you must authenticate:

Generate a GitHub Personal Access Token:
- Go to GitHub → Settings → Developer settings → Personal access tokens
- Create token with at least read:packages scope
- Copy the generated token
Authenticate npm:

npm login --registry=https://npm.pkg.github.com

Username: Your GitHub username
Password: Your GitHub personal access token
Email: Your GitHub email

Install Dependencies

rush install

3. Configuration

Environment Variables

While the README doesn't specify exact environment variables, based on the architecture you'll likely need:

Database configuration (MongoDB/PostgreSQL)
Storage configuration (for blob storage)
Email/SMTP settings for notifications
Authentication providers (OAuth, SSO)
API keys for integrated services

Configuration Files

Key configuration areas based on source files:

Notification System (server-plugins/notification-resources/src/index.ts):
- Configure notification templates and delivery methods
- Set up email/SMS/webhook integrations
Backup System (server/backup/src/utils.ts):
- Configure backup storage (S3, local, etc.)
- Set backup schedules and retention policies
Database Models (models/recruit/src/index.ts):
- Customize data models for your use case
- Configure application-specific settings

Self-Hosting Configuration

For production self-hosting without development, use the dedicated repository:

git clone https://github.com/hcengineering/huly-selfhost.git
cd huly-selfhost

This provides Docker-based deployment with pre-configured settings.

4. Build & Run

Development Mode (Fast Start)

For quick local development setup:

./scripts/fast-start.sh

Manual Build Process

Build all packages:

rush build

Build and watch for changes:

rush build:watch

Run in development mode:

rush start:dev

Update Project Structure and Database

After making model changes:

rush update:models

Production Build

rush build:production

5. Deployment

Self-Hosting with Docker (Recommended)

For production deployments, use the official self-hosting repository:

git clone https://github.com/hcengineering/huly-selfhost.git
cd huly-selfhost
docker compose up -d

This includes:

Pre-configured Docker Compose setup
Database (MongoDB/PostgreSQL)
Storage services
Reverse proxy (Nginx/Traefik)
SSL/TLS configuration

Platform Recommendations

Based on the TypeScript/Node.js stack:

Cloud Platforms:
- AWS: ECS/EKS for container orchestration, RDS for database, S3 for storage
- Google Cloud: GKE for Kubernetes, Cloud SQL, Cloud Storage
- Azure: AKS, Azure Database, Blob Storage
- DigitalOcean: Kubernetes, Managed Databases, Spaces
Container Orchestration:
- Kubernetes: For scalable, production-grade deployments
- Docker Swarm: For simpler container orchestration
Database:
- MongoDB Atlas: Managed MongoDB service
- PostgreSQL: For relational data needs
- Redis: For caching and real-time features

Deployment Steps

Build Docker images:

docker build -t huly-platform:latest .

Configure environment: Create .env file with production variables:

NODE_ENV=production
DATABASE_URL=mongodb://...
STORAGE_PROVIDER=s3
S3_BUCKET=your-bucket

Deploy with Docker Compose:

docker compose -f docker-compose.prod.yml up -d

Set up reverse proxy (Nginx example):

server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

6. Troubleshooting

Common Issues and Solutions

1. Dependency Installation Failures

Issue: npm ERR! 404 Not Found when installing from GitHub Packages Solution:

Ensure you're authenticated: npm whoami --registry=https://npm.pkg.github.com
Verify token has read:packages scope
Clear npm cache: npm cache clean --force

2. Docker Compose Errors

Issue: Port conflicts or container startup failures Solution:

# Check for port conflicts
sudo lsof -i :3000

# Rebuild containers
docker compose down
docker compose build --no-cache
docker compose up -d

3. Database Connection Issues

Issue: Services can't connect to MongoDB/PostgreSQL Solution:

Verify database is running: docker ps | grep mongo
Check connection string format
Ensure network configuration allows inter-container communication

4. Rush Build Failures

Issue: Build errors in monorepo Solution:

# Clean and rebuild
rush purge
rush update
rush install
rush rebuild

5. Memory Issues

Issue: Node.js memory exhaustion during build Solution:

# Increase Node.js memory limit
export NODE_OPTIONS="--max-old-space-size=4096"
rush build

6. Submodule Issues

Issue: Communication submodule not updating Solution:

git submodule sync
git submodule update --init --recursive

7. WSL-Specific Issues

If using Windows Subsystem for Linux:

Ensure Docker Desktop WSL integration is enabled
Run Docker commands from WSL terminal
Check file permissions: chmod +x scripts/*.sh

Getting Help

Check the Architecture Overview for system design
Review the Changelog for recent changes
Use the API Client for programmatic access: API Client Docs
Explore examples: Huly Examples Repository

Version Considerations

Use v* tags (e.g., v0.7.310) for production
Use s* tags (e.g., s0.7.313) for development/testing only
Check GitHub Releases for stable versions

How to Deploy & Use platform