External Site Setup Guide

This guide walks you through setting up an external static site (portfolio or documentation portal) that consumes ZodBack public APIs.

Prerequisites

• A ZodBack project with enabled modules (Portfolio and/or Documentation)
• An API token with allowed origins configured
• A web server or static hosting (Netlify, Vercel, GitHub Pages, etc.)

Portfolio Site Setup

Step 1: Clone the Template

The portefolio/ directory in the ZodBack repository contains a ready-to-use vanilla HTML/JS portfolio site.

cp -r portefolio/ my-portfolio-site/
cd my-portfolio-site/

Step 2: Configure

Edit js/config.js:

export const CONFIG = {
  API_URL: 'https://api.yourdomain.com/api/portfolio/v1/public',
  API_TOKEN: 'your-api-token-here',
  PROJECT_ID: '1',
  THEME: 'light',
  CACHE_DURATION: 300000,
  SITE_TITLE: 'John Doe - Portfolio',
};

Step 3: Deploy

Upload to any static hosting provider. The site is pure HTML/CSS/JS with no build step required.

Documentation Portal Setup

Step 1: Copy the Template

cp -r docs-portal/ my-docs-site/
cd my-docs-site/

Step 2: Configure

Edit js/config.js:

export const DOC_CONFIG = {
  API_URL: 'https://api.yourdomain.com/api/docs/v1/public',
  API_TOKEN: 'your-api-token-here',
  PROJECT_ID: '1',
  THEME: 'light',
  CACHE_DURATION: 300000,
  SITE_TITLE: 'My Documentation',
  DEBUG: false,
};

Step 3: Deploy

Same as portfolio — no build step needed.

CORS Configuration

For your external site to work, ensure:

1. API Token has the correct allowed origins:

   • https://yourdomain.com for production
   • http://localhost:5500 for local development (VS Code Live Server)
   • http://localhost:3000 for local development (other servers)

2. Project ID matches the project the token belongs to

Testing Locally

Use any static file server:

# Python
python -m http.server 5500

# Node.js (npx)
npx serve .

# VS Code
# Install "Live Server" extension, right-click index.html → "Open with Live Server"

Customization

Changing the Theme

Both portals support light and dark themes via CSS variables. Edit css/style.css to customize:

:root, [data-theme="light"] {
  --bg: #ffffff;
  --accent: #3b82f6;
  /* ... */
}

[data-theme="dark"] {
  --bg: #0f172a;
  --accent: #60a5fa;
  /* ... */
}

Adding Custom Pages

For the docs portal, create pages through the dashboard:

1. Navigate to Documentation > Pages
2. Click Create Page
3. Write content in Markdown
4. Set status to Published and toggle Public
5. The page appears automatically in the external portal

Troubleshooting