Anatomy of a Workspace

A workspace is a containerized development environment that provides isolated, consistent infrastructure for your web applications. Understanding its structure will help you work more effectively within the platform.

Architecture Overview

graph TD
    Project["PROJECT<br/>Database server & /shared storage"]
    
    WS1["Workspace 1<br/>/home/web"]
    WS2["Workspace 2<br/>/home/web"]
    WS3["Workspace 3<br/>/home/web"]
    
    WS1 --db--> Project
    WS2 --db--> Project
    WS3 --db--> Project
    
    style Project fill:#3b82f6,stroke:#2563eb,stroke-width:4px,color:#fff,font-size:18px
    style WS1 fill:#8b5cf6,stroke:#7c3aed,stroke-width:3px,color:#fff,font-size:16px
    style WS2 fill:#8b5cf6,stroke:#7c3aed,stroke-width:3px,color:#fff,font-size:16px
    style WS3 fill:#8b5cf6,stroke:#7c3aed,stroke-width:3px,color:#fff,font-size:16px

Key Points:

• Each service runs in its own container but shares access to /home/web and /shared
• Services communicate via localhost within the workspace
• Multiple workspaces can exist per project, each with their own /home/web but sharing /shared and db
• Developers access workspaces via SSH but cannot directly interact with running service processes

Directory Structure

Every workspace provides two key directories for persistent storage:

/home/web

The home directory for the web user under which all workspace processes run.

• Web Root: Located at /home/web/html by default
• Flexibility: Can be a physical directory or symbolic link to another location under /home/web
• Storage: Limited capacity, configurable through the admin application
• Use Case: Application code, configuration files, and runtime data

/shared

A project-level directory shared across all workspaces in the same project.

• Capacity: Functionally unlimited storage
• Performance: Slower I/O compared to /home/web (not suitable for runtime operations)
• Primary Uses:
  • Share configuration files, database backups, and resources between team members
  • Store static assets (images, media files) that are symlinked into each workspace’s web root

File Persistence

These are the only directories where modifications persist. All other directories are owned by system users and any changes will be lost on workspace restart.

Service Architecture

A workspace consists of multiple containerized services running over persistent storage. While the exact configuration varies by project type, most workspaces include:

Core Services

Web Server

• Apache or Nginx
• Configured via the Workspace Manager admin application
• Serves files from the web root

SSH Server

• Provides secure shell access for developers
• Enables direct file manipulation and command execution

Application Runtime

• Language-specific runtime (e.g., php-fpm, Node.js, Python)
• Executes application code in response to HTTP requests

Optional Services

• Redis cache
• Local search engines
• Task queues
• Other project-specific services

Container Isolation

Each service runs in its own container while sharing access to /home/web and /shared directories. This architecture means:

• SSH sessions provide access to files, not running processes
• You cannot directly interact with the web server or application runtime processes
• Service configuration changes must be made through the Workspace Manager admin app
• Services communicate over the local network interface (localhost)

Testing Your Application

From an SSH session, you can test your application’s HTTP output using:

curl -H "Host: $WORKSPACE_DOMAIN_1" localhost

This shows exactly what the web server is serving.

Shared Project Services

Beyond the /shared directory, workspaces can access project-level services at the hostname db:

Database Access

• MySQL/PostgreSQL available at db:3306 or db:5432
• Shared across all workspaces in the project
• Enables consistent data access for development and testing

Connection Example

mysql -h db -u username -p database_name

Search Engine Access

• OpenSearch/Elasticsearch often available at db:9200
• Shared across all workspaces in the project
• No HTTPS or authentication required for internal access

Search Engine Example

# Check cluster health
curl http://db:9200/_cluster/health

# List all indices
curl http://db:9200/_cat/indices?v

# Search an index
curl http://db:9200/my-index/_search?q=*

# Get document by ID
curl http://db:9200/my-index/_doc/1

Best Practices

• Keep application code in /home/web for optimal performance
• Use /shared for large static assets and team resources
• Symlink shared assets into your web root as needed
• Remember that only /home/web and /shared persist across restarts
• Use the admin application for service configuration changes