User Guide: Publish Web Application - EyevinnOSC/community GitHub Wiki

User Guide: Publishing Web Applications in Open Source Cloud

This guide provides comprehensive instructions for publishing web applications built using open web services in Eyevinn Open Source Cloud (OSC). The instructions are designed to be clear for both human users and AI agents.

Overview

There are three main approaches for publishing web applications and servers in OSC:

  1. Static Website Publishing - For frontend-only applications (React, Vue, Angular, static sites)
  2. Full-Stack Application Publishing - For applications with backend services and databases
  3. MCP Server Hosting - Deploy a custom Model Context Protocol (MCP) server with a public HTTPS endpoint

Prerequisites

Before you begin, ensure you have:

  • An account on Eyevinn Open Source Cloud (sign up at https://app.osaas.io)
  • An API Access Token from Settings/API section in your OSC dashboard
  • Your token stored as environment variable: OSC_ACCESS_TOKEN
  • Node.js and npm installed (for CLI usage)
  • Git installed (for repository management)

Instance Naming Guidelines

Important: OSC instance names must follow these rules:

  • Only alphanumeric characters (a-z, A-Z, 0-9)
  • No hyphens (-), underscores (_), or special characters
  • Must start with a letter
  • Maximum length: typically 20-30 characters

Valid Examples: myapp, backend01, database, cache Invalid Examples: my-app, backend_01, my.app, 123app

Method 1: Static Website Publishing

Use this method for frontend-only applications such as React, Vue, Angular, or any static HTML/CSS/JS sites.

Step 1: Prepare Your Application

# Example with React application
npx create-react-app my-app
cd my-app

# Important: Set PUBLIC_URL for proper routing in OSC
# Replace 'myapp' with your actual application name
PUBLIC_URL=/myapp/ npm run build

For other frameworks:

# Vue.js
npm run build
# Output typically in 'dist' directory

# Angular
ng build --base-href /myapp/
# Output in 'dist/my-app' directory

# Static HTML/CSS/JS
# Ensure all assets use relative paths or absolute paths starting with /myapp/

Step 2: Install OSC CLI (if not already installed)

npm install -g @osaas/cli@latest

Step 3: Set Up Authentication

# Set your access token (get from OSC dashboard Settings/API)
export OSC_ACCESS_TOKEN=your_token_here

# Verify authentication
npx @osaas/cli@latest auth status

Step 4: Deploy to OSC

# Deploy the build directory
npx @osaas/cli@latest web publish myapp build/

# For other frameworks, adjust the directory:
# Vue: npx @osaas/cli@latest web publish myapp dist/
# Angular: npx @osaas/cli@latest web publish myapp dist/my-app/

Step 5: Access Your Application

After successful deployment, you'll receive:

  • A unique URL where your application is hosted: https://myapp--[unique-id].app.osaas.io
  • CDN URL for global distribution

Step 6: Optional CDN Configuration

Configure CDN settings in OSC dashboard for:

  • Custom domain mapping
  • Cache control settings
  • SSL certificate management
  • Geographic distribution

Method 2: Full-Stack Application Publishing

Use this method for applications with backend services, databases, or server-side logic.

Step 1: Create Required Backend Services

First, create any backend services your application needs using OSC CLI or dashboard:

# Create a PostgreSQL database
npx @osaas/cli@latest create birme-osc-postgresql mydb \
  -o username=myuser \
  -o password=mypassword \
  -o database=myappdb

# Create a Valkey (Redis-compatible) cache
npx @osaas/cli@latest create valkey-io-valkey mycache

# Create other services as needed:
# - MariaDB: npx @osaas/cli@latest create linuxserver-docker-mariadb mymariadb -o username=user -o password=pass -o database=mydb
# - ClickHouse: npx @osaas/cli@latest create clickhouse-clickhouse myanalytics -o user=user -o password=pass
# - MinIO: npx @osaas/cli@latest create minio-minio mystorage -o rootUser=admin -o rootPassword=pass

Available OSC Services:

  • Databases: PostgreSQL, MariaDB, ClickHouse, CouchDB
  • Caching: Valkey (Redis-compatible), DiceDB
  • Storage: MinIO (S3-compatible)
  • Message Queues: SmoothMQ, Really Simple Message Queue
  • Media Processing: FFmpeg, Encore (transcoding)
  • Analytics: Umami, Matomo, Plausible

Step 2: Prepare Your Application Repository

# Ensure your application is in a GitHub repository
git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/yourusername/your-app.git
git push -u origin main

# Create a Dockerfile (if your app doesn't have one)
cat > Dockerfile << EOF
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
EXPOSE 3000
CMD ["npm", "start"]
EOF

Step 3: Deploy with Web Runner Service

# Create a Web Runner instance to deploy your app from GitHub
npx @osaas/cli@latest create eyevinn-web-runner myapp \
  -o sourceUrl=https://github.com/yourusername/your-app.git \
  -o githubToken=your_github_token

# Alternative: Use OSC dashboard to create Web Runner service
# Navigate to Services > Create Service > Web Runner

Step 4: Configure Environment Variables and Secrets

# Create secrets for sensitive data
npx @osaas/cli@latest secrets create myapp DATABASE_PASSWORD mypassword
npx @osaas/cli@latest secrets create myapp API_KEY your_api_key

# Set environment variables through the dashboard or CLI
# Common environment variables for web applications:
# - DATABASE_URL=postgresql://user:pass@host:port/db
# - REDIS_URL=redis://host:port
# - NODE_ENV=production
# - PORT=3000

Step 5: Link Services and Deploy

# Get connection URLs for your services
npx @osaas/cli@latest describe birme-osc-postgresql mydb
npx @osaas/cli@latest describe valkey-io-valkey mycache

# Update your application's environment variables with service URLs
# Deploy or redeploy your Web Runner instance
npx @osaas/cli@latest restart eyevinn-web-runner myapp

Step 6: Verify Deployment

# Check service status
npx @osaas/cli@latest describe eyevinn-web-runner myapp

# View logs
npx @osaas/cli@latest logs eyevinn-web-runner myapp

# Get the application URL
npx @osaas/cli@latest describe eyevinn-web-runner myapp

Method 3: MCP Server Hosting

Use this method to host a custom Model Context Protocol (MCP) server on OSC and expose it via a public HTTPS endpoint. This lets AI agents (Claude, Cursor, VS Code, etc.) connect to your server from anywhere.

Prerequisites

  • Your MCP server is in a git repository on any HTTPS git host (GitHub, GitLab, Gitea, or self-hosted)
  • The server is written in Node.js, Python, or WebAssembly
  • It exposes an HTTP transport endpoint (e.g. /mcp)

Step 1: Push your MCP server to a git repository

Ensure your repository has a Dockerfile or follows a standard project layout that OSC's My Apps runtime can build.

Step 2: Deploy via My Apps

  1. Go to app.osaas.io/dashboard/my-apps
  2. Click Add application
  3. Choose I have a git repository and enter your git repository URL (any HTTPS URL — GitHub, GitLab, Gitea, etc.), or choose I need a git repository to have OSC provision one for you
  4. Select the runtime (Node.js, Python, or WebAssembly)
  5. Give the app a name (alphanumeric only, e.g. mymcpserver)
  6. Click Deploy

Monorepo support: If your server lives in a subdirectory of a larger repository (e.g. packages/my-mcp-server), specify the subdirectory path in the Sub Path field when creating the app. The build will run from that subdirectory instead of the repository root.

Note: .osc.yaml configuration files are not currently supported. Apps are built from the repository root (or the specified sub path) using the Dockerfile or standard runtime conventions.

OSC builds and deploys your server automatically. Once running, it receives a public HTTPS URL:

https://<appname>.auto.prod.osaas.io

Step 3: Connect AI agents to your MCP server

Use the public URL as the MCP endpoint. For example in Claude Code:

claude mcp add --transport http mymcp https://<appname>.auto.prod.osaas.io/mcp

Or in ~/.cursor/mcp.json:

{
  "mcpServers": {
    "mymcp": {
      "type": "http",
      "url": "https://<appname>.auto.prod.osaas.io/mcp"
    }
  }
}

For a full step-by-step tutorial, see Deploy an MCP Server on OSC on the OSC website.

AI Agent Instructions

For AI agents assisting with deployment, follow this systematic approach:

1. Application Analysis

# Identify application type by checking for:
ls -la                          # Look for package.json, Dockerfile, etc.
cat package.json               # Check dependencies and scripts
find . -name "*.html" -o -name "*.js" -o -name "*.css"  # Static files
find . -name "server.js" -o -name "app.js" -o -name "index.js"  # Backend files

Decision Matrix:

  • Static Only: No server files, only HTML/CSS/JS or build output � Use Method 1
  • Full-Stack: Has server files, database dependencies, API endpoints � Use Method 2

2. Prerequisites Verification

# Check OSC CLI installation
npx @osaas/cli@latest --version

# List available services (if backend needed)
npx @osaas/cli@latest list

3. Deployment Execution

For Static Applications:

# Build the application
npm run build  # or appropriate build command

# Deploy to OSC
npx @osaas/cli@latest web publish ${APPNAME} ${BUILD_DIR}/

For Full-Stack Applications:

# Create required services first
npx @osaas/cli@latest create ${SERVICE_TYPE} ${SERVICENAME}

# Deploy application
npx @osaas/cli@latest create eyevinn-web-runner ${APPNAME} \
  -o sourceUrl=${GITHUB_URL}

For Monorepo Applications (via MCP create-my-app tool):

When the application is in a subdirectory of the repository, pass the subPath parameter:

"Create a Node.js app called myapp from https://github.com/org/monorepo with sub path packages/backend"

The MCP tool will set subPath=packages/backend so the build runs from that directory.

4. Post-Deployment Verification

# Check deployment status
npx @osaas/cli@latest describe eyevinn-web-runner ${APPNAME}

# Test application endpoint
curl -I ${APP_URL}

# Monitor logs for errors
npx @osaas/cli@latest logs eyevinn-web-runner ${APPNAME}

5. Error Handling

  • Authentication Failed: Verify OSC_ACCESS_TOKEN is set correctly
  • Build Errors: Check local build first with npm run build
  • Service Creation Failed: Verify service name uniqueness
  • Deployment Failed: Check repository accessibility and Dockerfile validity

Troubleshooting

Common Issues:

  • Invalid Token: Ensure OSC_ACCESS_TOKEN is correctly set
  • Build Errors: Verify application builds successfully locally
  • Routing Issues: Check PUBLIC_URL setting for static sites
  • Service Dependencies: Ensure all required services are created and configured

Getting Help:

  • Join the community Slack: https://slack.osaas.io
  • Check OSC documentation
  • Contact support through OSC dashboard

Best Practices

  1. Version Control: Always use version control for your applications
  2. Environment Variables: Use environment variables for configuration
  3. Security: Never commit secrets to repositories
  4. Testing: Test applications locally before deployment
  5. Monitoring: Set up monitoring for production applications

Complete Examples

Example 1: React Application with API Backend

Step-by-step deployment of a React app with Node.js backend:

# 1. Create and prepare the application
npx create-react-app myfullstackapp
cd myfullstackapp

# 2. Add backend dependencies to package.json
npm install express cors dotenv

# 3. Create basic Express server (server.js)
cat > server.js << 'EOF'
const express = require('express');
const cors = require('cors');
require('dotenv').config();

const app = express();
const PORT = process.env.PORT || 3001;

app.use(cors());
app.use(express.json());

app.get('/api/health', (req, res) => {
  res.json({ status: 'OK', timestamp: new Date().toISOString() });
});

app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});
EOF

# 4. Update package.json scripts
npm pkg set scripts.server="node server.js"
npm pkg set scripts.dev="concurrently \"npm start\" \"npm run server\""

# 5. Create Dockerfile
cat > Dockerfile << 'EOF'
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
EXPOSE 3001
CMD ["npm", "run", "server"]
EOF

# 6. Initialize git and push to GitHub
git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/yourusername/myfullstackapp.git
git push -u origin main

# 7. Deploy backend with Web Runner
export OSC_ACCESS_TOKEN=your_token_here
npx @osaas/cli@latest create eyevinn-web-runner myappbackend \
  -o sourceUrl=https://github.com/yourusername/myfullstackapp.git

# 8. Build and deploy frontend
PUBLIC_URL=/myappfrontend/ npm run build
npx @osaas/cli@latest web publish myappfrontend build/

Example 2: Static Website with Database Integration

Deploying a static site that fetches data from OSC services:

# 1. Create database service
npx @osaas/cli@latest create birme-osc-postgresql mydatadb \
  -o username=datauser \
  -o password=securepass123 \
  -o database=appdata

# 2. Create API service to expose database
npx @osaas/cli@latest create eyevinn-web-runner myapi \
  -o sourceUrl=https://github.com/yourusername/myapi.git

# 3. Deploy static frontend
npx @osaas/cli@latest web publish mystaticapp dist/

# 4. Configure API endpoint in frontend
# Update your frontend code to use: https://myapi--[id].app.osaas.io/api

Example 3: E-commerce Application with Multiple Services

Complete e-commerce setup with database, cache, and storage:

# 1. Create all required services
npx @osaas/cli@latest create birme-osc-postgresql ecommercedb \
  -o username=ecomuser \
  -o password=ecompass123 \
  -o database=ecommerce

npx @osaas/cli@latest create valkey-io-valkey ecommercecache

npx @osaas/cli@latest create minio-minio ecommercestorage \
  -o rootUser=admin \
  -o rootPassword=adminpass123

# 2. Create secrets for sensitive data
npx @osaas/cli@latest secrets create ecommerceapp DB_PASSWORD ecompass123
npx @osaas/cli@latest secrets create ecommerceapp STRIPE_SECRET_KEY sk_test_xxx
npx @osaas/cli@latest secrets create ecommerceapp JWT_SECRET your_jwt_secret

# 3. Deploy the application
npx @osaas/cli@latest create eyevinn-web-runner ecommerceapp \
  -o sourceUrl=https://github.com/yourusername/ecommerceapp.git

# 4. Get service URLs and update environment variables
npx @osaas/cli@latest describe birme-osc-postgresql ecommercedb
npx @osaas/cli@latest describe valkey-io-valkey ecommercecache
npx @osaas/cli@latest describe minio-minio ecommercestorage

This guide ensures both users and AI agents can successfully publish web applications in Eyevinn Open Source Cloud using open web services.

⚠️ **GitHub.com Fallback** ⚠️