The playground.digital.auto is an open, web-based prototyping environment designed for developing Software-Defined Vehicle (SDV) solutions.

The playground consists of some primary components:

• Frontend: autowrx repo: Frontend application built with Vite and React
• Backend: backend-core repo: Backend services built with Node.js, Express, and MongoDB
• Inventory: inventory repo: Schema and instance data management system
• API Gateway: playground-kong repo: Kong-based API gateway for request routing and management

The entire platform is containerized using Docker, making it easy to deploy and develop across different environments.

.
├── autowrx/                  # Frontend application
├── backend-core/             # Core backend services
├── inventory/                # Schema and instance management
├── playground-kong/          # Kong API gateway configuration
├── docker-compose.yml        # Base Docker Compose configuration
├── docker-compose.dev.yml    # Development environment configuration
├── docker-compose.prod.yml   # Production environment configuration
└── nginx.conf                # Nginx configuration

Before setting up your playground instance, ensure you have the following installed:

• Docker and Docker Compose
• Git (for cloning repositories)

• Node.js (v18+)
• Yarn package manager

Memory Usage Note: The KONG_SVC_NGINX_WORKER_PROCESSES variable defaults to auto, which creates worker processes based on your CPU cores. This will consume memory proportional to your system specifications. If you're working with limited memory, you can reduce this by setting it to a specific number (e.g., 1 or 2) in your .env file.

1. Clone the repository:

   git clone https://github.com/eclipse-autowrx/instance-setup playground
   cd playground

2. Initialize Submodules (Optional for Development):

   If you plan to do local development:

   git submodule update --init --remote --recursive

3. Set up environment variables for development:

   Create .env file from .env.example template:

   cp .env.example .env

   The default values in .env.example are suitable for development environments.

4. Start the Development Platform:

   ./start.sh

3. Set up environment variables for production:

   Create .env file from .env.example template:

   cp .env.example .env

   ⚠️ Important Production Configuration:

   Before starting the production environment, you must edit the .env file and update the following variables:

   • JWT_COOKIE_DOMAIN: Set this to match your production domain.
     • Example: yourdomain.com
     • Important: Use only the domain name without the protocol scheme.
       • ❌ Invalid: https://yourdomain.com
       • ✅ Valid: yourdomain.com
   • NODE_ENV: Set to production
   • Security variables: Update any default passwords, secrets, or API keys
   • (Optional) Database configuration: Configure production database settings if using external databases

4. Start the Production Platform:

   ./start.sh -prod -d

Frontend environment variables are embedded into the Docker image at build time. This means:

• Environment variables for the frontend service are baked into the image during the Docker build process
• If you modify any frontend-related environment variables in your .env file after the initial setup, you must rebuild the Docker image for changes to take effect

To apply frontend environment variable changes:

# Stop the current containers
docker compose down

# Rebuild with the updated environment variables
./start.sh -b

Examples of frontend environment variables that require rebuilding:

• API endpoint URLs
• Feature flags
• Build-time configuration variables
• Any variables prefixed with VITE_ or REACT_APP_

Backend environment variables are loaded at runtime and do not require image rebuilding.

Once the containers are running, you can access:

When running in development mode, additional services are available:

The backend APIs are documented using Swagger/OpenAPI:

• Inventory API: http://localhost:3000/api/v2/inventory/docs

• All API endpoints are secured with JWT authentication
• Sensitive environment variables should be properly secured in production

This section includes troubleshooting tips you might find helpful when setting up your Playground instance

Problem: Changes to code aren't reflected in running containers.

Solution: Rebuild images with the --build flag:

docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build

Problem: Error message about containers already existing.

Solutions:

Option 1: Use project names to avoid conflicts:

docker compose --project-name my-playground -f docker-compose.yml -f docker-compose.dev.yml up

Option 2: Remove existing containers:

docker compose down
docker container prune

Copyright (c) 2025 Robert Bosch GmbH.

This program and the accompanying materials are made available under the terms of the MIT License which is available at https://opensource.org/licenses/MIT.

SPDX-License-Identifier: MIT