igny8/DEPLOYMENT_GUIDE.md

Site Deployment Guide

How Site Deployment Works

Overview

When you deploy a site blueprint, the system:

1. Builds a site definition (merging Content from Writer into PageBlueprint blocks)
2. Writes it to the filesystem at /data/app/sites-data/clients/{site_id}/v{version}/
3. The Sites Renderer reads from this filesystem to serve the public site

Deployment Process

Step 1: Prepare Your Site

1. Generate Structure: Create site blueprint with pages (has placeholder blocks)
2. Generate Content: Pages → Tasks → Content (Writer generates real content)
3. Publish Content: In Content Manager, set Content status to 'publish' for each page
4. Publish Pages: In Page Manager, set Page status to 'published' (for navigation)

Step 2: Deploy the Blueprint

API Endpoint: POST /api/v1/publisher/deploy/{blueprint_id}/

What Happens:

• SitesRendererAdapter.deploy() is called
• For each page, it finds the associated Writer Task
• If Content exists and is published, it uses Content.json_blocks instead of blueprint placeholders
• Builds complete site definition with all pages
• Writes to filesystem: /data/app/sites-data/clients/{site_id}/v{version}/site.json
• Creates deployment record

Step 3: Access Your Site

Public URL: https://sites.igny8.com/{siteSlug}

How It Works:

• Sites Renderer loads site definition from filesystem (or API fallback)
• Shows navigation menu with all published pages
• Home route (/siteSlug) shows only home page content
• Page routes (/siteSlug/pageSlug) show specific page content

Navigation Menu

The navigation menu automatically includes:

• Home link (always shown)
• All pages with status 'published' or 'ready' (excluding home)
• Pages are sorted by their order field

Page Routing

• Homepage: https://sites.igny8.com/{siteSlug} → Shows home page only
• Individual Pages: https://sites.igny8.com/{siteSlug}/{pageSlug} → Shows that specific page
  • Example: https://sites.igny8.com/auto-g8/products
  • Example: https://sites.igny8.com/auto-g8/blog

Content Merging

When deploying:

• If Content is published: Uses Content.json_blocks (actual written content)
• If Content not published: Uses PageBlueprint.blocks_json (placeholder blocks)
• Content takes precedence: Published Content always replaces blueprint placeholders

Important Notes

1. Two Statuses:

   • PageBlueprint.status = 'published' → Controls page visibility in navigation
   • Content.status = 'publish' → Controls which content is used (real vs placeholder)

2. Redeploy Required: After publishing Content, you must redeploy the site for changes to appear

3. All Pages Deployed: The deployment includes ALL pages from the blueprint, but only published pages show in navigation

4. Navigation Auto-Generated: If no explicit navigation is set in blueprint, it auto-generates from published pages

Troubleshooting

Problem: Navigation only shows "Home"

• Solution: Make sure other pages have status 'published' or 'ready' in Page Manager

Problem: Pages show placeholder content instead of real content

• Solution:
  1. Check Content status is 'publish' in Content Manager
  2. Redeploy the site blueprint

Problem: Pages not accessible via URL

• Solution: Make sure pages have status 'published' or 'ready' and the site is deployed