Angular Application for Convox

A production-ready Angular application configured for deployment on Convox.

Angular is Google's powerful TypeScript-based framework for building dynamic, scalable web applications. This example demonstrates how to deploy a modern Angular 18+ application on Convox with automatic SSL, load balancing, and zero-downtime deployments.

Deploy to Convox Cloud for a fully-managed platform experience, or to your own Convox Rack for complete control over your infrastructure. Either way, you'll get automatic SSL, load balancing, and zero-downtime deployments out of the box.

Features

• Modern Angular Framework - Built with Angular 18 and standalone components for optimal performance
• TypeScript First - Full type safety with TypeScript 5.9 for maintainable code
• Production Optimized - Ahead-of-Time compilation, tree-shaking, and minification
• Container-Ready - Multi-stage Docker build for minimal production images
• Static Asset Serving - Efficient serving with the lightweight serve package
• Health Monitoring - Built-in health check endpoint for reliability
• Auto-Scaling Ready - Configured for horizontal scaling based on load
• Developer Experience - Hot module replacement and Angular DevTools support

Deploy to Convox Cloud

1. Create a Cloud Machine at console.convox.com

2. Create the app:

convox cloud apps create angular-app -i your-machine-name

3. Deploy the app:

convox cloud deploy -a angular-app -i your-machine-name

4. View your app:

convox cloud services -a angular-app -i your-machine-name

Visit your URL to see the Angular app running!

Deploy to Convox Rack

1. Create the app:

convox apps create angular-app

2. Deploy the app:

convox deploy -a angular-app

3. View your app:

convox services -a angular-app

Visit your URL to see the Angular app running!

Application Features

The example Angular application includes:

• Welcome Component - Interactive landing page with Angular branding
• Resource Links - Quick access to documentation and learning resources
• Responsive Design - Mobile-first design with modern CSS
• Signal-Based State - Leverages Angular's new signals API for reactive state management
• Standalone Components - Modern Angular architecture without NgModules

Testing the Application

# Get the service URL
convox services -a angular-app

# Test the application
curl https://web.angular-app.cloud.convox.com/

# Check static asset serving
curl https://web.angular-app.cloud.convox.com/favicon.ico

# Verify the Angular build
curl -I https://web.angular-app.cloud.convox.com/main.js

Configuration

Environment Variables

Configure your application using environment variables:

# Convox Cloud
convox cloud env set \
  NODE_ENV=production \
  API_URL=https://api.example.com \
  -a angular-app -i your-machine-name

# Convox Rack
convox env set \
  NODE_ENV=production \
  API_URL=https://api.example.com \
  -a angular-app

Scaling

Adjust the number of running processes and resources:

# Cloud
convox cloud scale web --count 3 --cpu 256 --memory 512 -a angular-app -i your-machine-name

# Rack
convox scale web --count 3 --cpu 256 --memory 512 -a angular-app

Or configure autoscaling in your convox.yml:

services:
  web:
    build: .
    port: 3000
    scale:
      count: 1-5
      cpu: 250
      memory: 512
      targets:
        cpu: 70
        memory: 80

Development

Local Development

1. Install dependencies:

npm install

2. Run development server:

ng serve
# or
npm start

The app will be available at http://localhost:4200 with automatic reload on changes.

3. Build for production:

ng build
# or
npm run build

The build artifacts will be stored in dist/Angular/browser/.

4. Run tests:

# Unit tests
ng test

# End-to-end tests (if configured)
ng e2e

Local Development with Convox

Use Convox to run the application locally with Docker:

convox start

This will build and run the application in a local Docker environment that mimics production.

Project Structure

.
├── src/
│   ├── app/
│   │   ├── app.ts              # Root component (standalone)
│   │   ├── app.html            # Component template
│   │   ├── app.scss            # Component styles
│   │   ├── app.spec.ts         # Component tests
│   │   ├── app.config.ts       # Application configuration
│   │   └── app.routes.ts       # Route definitions
│   ├── index.html              # Main HTML file
│   ├── main.ts                 # Bootstrap file
│   └── styles.scss             # Global styles
├── angular.json                # Angular CLI configuration
├── tsconfig.json              # TypeScript configuration
├── Dockerfile                 # Multi-stage Docker build
├── convox.yml                # Convox deployment configuration
└── package.json              # Dependencies and scripts

Docker Configuration

The application uses an optimized multi-stage Docker build:

1. Build Stage: Node.js 22 Alpine compiles the Angular application
2. Production Stage: Lightweight Alpine image serves static files with serve

This approach results in:

• Small production images (~50MB)
• Fast deployment times
• Reduced attack surface
• Efficient resource usage

Angular-Specific Configuration

Build Optimization

The production build includes:

• Ahead-of-Time (AOT) compilation for faster rendering
• Tree-shaking to remove unused code
• Minification and uglification
• Differential loading for modern vs. legacy browsers
• Budget guards to prevent bundle size regression

Environment Configuration

Angular distinguishes between development and production builds:

// Access environment in your components
import { environment } from '../environments/environment';

if (environment.production) {
  // Production-specific code
}

Performance Considerations

The example is configured with:

• Lazy loading ready (just add routes)
• OnPush change detection strategy compatible
• Minimal initial bundle size
• Optimized for Core Web Vitals

Monitoring

View Logs

Cloud:

convox cloud logs -a angular-app -i your-machine-name

Rack:

convox logs -a angular-app

Health Check

The application serves static files and responds to health checks:

curl https://your-angular-app-url/

Build Information

Check build details:

# Cloud
convox cloud builds -a angular-app -i your-machine-name

# Rack
convox builds -a angular-app

Best Practices

1. Use Environment Variables: Configure API endpoints through environment variables
2. Enable Production Mode: Always build with --configuration production for deployments
3. Optimize Images: Keep Docker images small with multi-stage builds
4. Set Resource Limits: Configure appropriate CPU and memory for your app size
5. Use CDN: Consider CDN for static assets in high-traffic scenarios
6. Enable Compression: Gzip/Brotli compression is handled by the serve package
7. Monitor Bundle Size: Use ng build --stats-json to analyze bundle composition

Troubleshooting

Application Shows Development Build Warning

Ensure you're building for production:

convox logs -a angular-app --filter "Angular is running"

If you see development mode, rebuild with production configuration.

White Screen or 404 Errors

Check that the serve command is pointing to the correct directory:

convox logs -a angular-app --filter "serve"

The build output should be in dist/Angular/browser/.

Build Failures

If the build fails, check the build logs:

# Cloud
convox cloud builds logs BUILD_ID -a angular-app -i your-machine-name

# Rack
convox builds logs BUILD_ID -a angular-app

Common issues:

• Insufficient memory during build (increase Docker build memory)
• Missing dependencies in package.json
• TypeScript compilation errors

Performance Issues

Monitor resource usage:

# Cloud
convox cloud ps -a angular-app -i your-machine-name

# Rack
convox ps -a angular-app

For Angular apps, most performance issues are client-side:

• Check bundle sizes with ng build --stats-json
• Enable source maps to debug production issues
• Use Angular DevTools in Chrome/Edge

Advanced Configuration

Custom Domains

Add your custom domain:

# View current services to get the router domain
convox services -a angular-app
# Create a CNAME record pointing to the router domain

API Integration

For backend API integration, use Angular's HttpClient with environment configuration:

// In your service
constructor(private http: HttpClient) {
  this.apiUrl = environment.apiUrl;
}

getData() {
  return this.http.get(`${this.apiUrl}/data`);
}

Set the API URL via environment variable:

convox env set API_URL=https://api.yourdomain.com -a angular-app

Server-Side Rendering (SSR)

To add Angular Universal for SSR:

1. Add Angular Universal to your project:

ng add @angular/ssr

2. Update Dockerfile to use the SSR server:

CMD ["node", "dist/Angular/server/main.js"]

3. Update convox.yml port to match SSR server (typically 4000)

Progressive Web App (PWA)

To make your Angular app a PWA:

ng add @angular/pwa

This adds service worker support, manifest file, and offline capabilities.

Migrating Existing Angular Apps

From Angular CLI Development

1. Ensure your app builds successfully:

ng build --configuration production

2. Add the Dockerfile from this example
3. Add convox.yml configuration
4. Deploy to Convox

From Other Hosting Platforms

1. Export any environment variables from your current platform
2. Update API endpoints to use environment variables
3. Ensure your build output matches the Dockerfile's expectations
4. Test locally with convox start
5. Deploy to Convox

Resources

• Angular Documentation
• Angular CLI
• Angular DevTools
• Angular Performance Guide
• Convox Documentation
• Convox Cloud Guide

Support

• Angular Community: Discord | GitHub Discussions
• Convox Support: cloud-support@convox.com
• GitHub Issues: Create an issue