Apps Configuration

Configure applications in your Genbox environment.

Basic App Definition


apps:
  myapp:
    path: ./src                # Relative path from project root
    type: backend              # App type
    port: 3000                 # Port number

Full App Configuration


apps:
  api:
    # Required fields
    path: ./api
    type: backend
 
    # Optional fields
    port: 3050
    framework: nestjs
    runner: pm2
    description: Backend API services
 
    # Commands
    commands:
      install: pnpm install
      dev: pnpm run start:dev
      build: pnpm run build
      start: pnpm run start:prod
      test: pnpm test
      lint: pnpm lint
 
    # Dependencies
    connects_to:
      mongodb:
        mode: local
        env:
          MONGODB_URI: mongodb://localhost:27017/mydb
      redis:
        mode: staging
        required: false
 
    # Environment files
    env:
      - .env
      - .env.local
 
    # Health check
    healthcheck: /health
 
    # Docker configuration (if runner: docker)
    docker:
      file: docker-compose.yml
      service: api
      build_context: .

App Types

Frontend

Client-side applications:


apps:
  web:
    path: ./web
    type: frontend
    port: 3000
    framework: nextjs
    commands:
      dev: pnpm dev
      build: pnpm build
      start: pnpm start

Backend

Server-side applications:


apps:
  api:
    path: ./api
    type: backend
    port: 3050
    framework: nestjs
    commands:
      dev: pnpm run start:dev
      build: pnpm run build
      start: pnpm run start:prod

Worker

Background workers:


apps:
  worker:
    path: ./worker
    type: worker
    runner: pm2
    commands:
      start: pnpm run worker

Gateway

API gateways:


apps:
  gateway:
    path: ./gateway
    type: gateway
    port: 8080
    commands:
      start: pnpm start

Framework Detection

Genbox auto-detects frameworks from your dependencies:

Framework	Detection
Next.js	`next` in dependencies
React	`react` in dependencies
Vue	`vue` in dependencies
NestJS	`@nestjs/core` in dependencies
Express	`express` in dependencies
Fastify	`fastify` in dependencies

Use $detect for automatic detection:


apps:
  web:
    path: ./web
    type: frontend
    framework: $detect    # Auto-detect from package.json
    port: $detect         # Auto-detect from scripts

Connections

Define how apps connect to dependencies:


apps:
  web:
    type: frontend
    connects_to:
      api:
        mode: local              # Use local API
        env:
          NEXT_PUBLIC_API_URL: http://localhost:3050
 
      analytics:
        mode: staging            # Connect to staging
        required: false          # Optional dependency
        env:
          ANALYTICS_URL: https://analytics.staging.example.com

Connection Modes

Mode	Description
`local`	Use local service
`staging`	Connect to staging environment
`production`	Connect to production
`mock`	Use mock service

Environment Variables

From Files


apps:
  api:
    env:
      - .env                    # Load .env file
      - .env.local              # Override with local
      - .env.${NODE_ENV}        # Environment-specific

Inline


apps:
  api:
    connects_to:
      mongodb:
        mode: local
        env:
          MONGODB_URI: mongodb://localhost:27017/mydb
          MONGODB_DB_NAME: mydb

Docker Apps

For apps that run via Docker:


apps:
  api:
    path: ./api
    type: backend
    runner: docker
    docker:
      file: docker-compose.yml    # Docker compose file
      service: api                # Service name
      build_context: .            # Build context
      dockerfile: Dockerfile.dev  # Optional: Custom Dockerfile

Health Checks

Configure health check endpoints:


apps:
  api:
    port: 3050
    healthcheck: /health        # GET request to this path
 
    # Or with full configuration
    healthcheck:
      path: /health
      interval: 30s
      timeout: 5s
      retries: 3

Dependencies Between Apps

Define startup order:


apps:
  web:
    type: frontend
    depends_on:
      - api                     # Start after API is healthy
 
  api:
    type: backend
    depends_on:
      - mongodb                 # Start after MongoDB
      - redis

Best Practices

Use explicit ports: Avoid relying on auto-detection
Define health checks: Enable proper status monitoring
Specify commands: Don’t rely on package.json defaults
Document connections: Be explicit about dependencies
Use env files: Keep secrets out of genbox.yaml