Onboarding a New Site

Partner Documentation

This guide walks you through the complete process of adding a new customer site to DCS using the official npm packages.

Prerequisites

Before starting, ensure you have:

[ ] A VitePress or compatible website
[ ] Access to the site's GitHub repository
[ ] Node.js >= 18.0.0 installed
[ ] DCS partner account with admin access
[ ] Azure subscription with appropriate permissions (for deployment)

Quick Start (Recommended)

The fastest way to onboard a site is using the official CLI:

bash

# 1. Install the CLI globally
npm install -g @duffcloudservices/cli

# 2. Authenticate with DCS
dcs login

# 3. Navigate to your site's repository
cd /path/to/customer-site

# 4. Initialize DCS integration
dcs init --site-slug customer-site --site-name "Customer Site Name"

# 5. Install the CMS package
pnpm add @duffcloudservices/cms

# 6. Follow the generated integration plans
code .plans/

The CLI creates all necessary configuration files and generates step-by-step integration plans.

Step 1: Initialize DCS Configuration

Using the CLI (Recommended)

bash

dcs init --site-slug customer-site --site-name "Customer Site Name"

This creates:

.dcs/site.yaml — Site identity
.dcs/pages.yaml — Page registry
.dcs/content.yaml — Text content (portal-managed)
.dcs/seo.yaml — SEO configuration (portal-managed)
.github/copilot-instructions.md — AI assistant context
.plans/ — Integration guides

Manual Setup (Alternative)

If you prefer manual setup, create .dcs/config.yaml:

yaml

site:
  slug: customer-site
  name: Customer Site Name

api:
  endpoint: https://portal.duffcloudservices.com/api

features:
  textOverrides: true
  seoMetadata: true
  blog: true
  analytics: true

Step 2: Install & Configure the CMS Package

Install Dependencies

bash

pnpm add @duffcloudservices/cms

Configure Vite Plugins

For VitePress sites:

typescript

// .vitepress/config.ts
import { defineConfig } from 'vitepress'
import { dcsContentPlugin, dcsSeoPlugin } from '@duffcloudservices/cms/plugins'

export default defineConfig({
  vite: {
    plugins: [
      dcsContentPlugin(),
      dcsSeoPlugin()
    ]
  }
})

For standard Vite sites:

typescript

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { dcsContentPlugin, dcsSeoPlugin } from '@duffcloudservices/cms/plugins'

export default defineConfig({
  plugins: [
    vue(),
    dcsContentPlugin(),
    dcsSeoPlugin()
  ]
})

Add Environment Variables

bash

# .env
VITE_SITE_SLUG=customer-site
VITE_API_BASE_URL=https://portal.duffcloudservices.com

Step 3: Implement Text Content Integration

Use the Composable

vue

<script setup lang="ts">
import { useTextContent } from '@duffcloudservices/cms'

const { t } = useTextContent({
  pageSlug: 'home',
  defaults: {
    'hero.title': 'Welcome to Our Site',
    'hero.subtitle': 'Building the future together',
    'cta.primary': 'Get Started'
  }
})
</script>

<template>
  <section class="hero">
    <h1>{{ t('hero.title') }}</h1>
    <p>{{ t('hero.subtitle') }}</p>
    <button>{{ t('cta.primary') }}</button>
  </section>
</template>

Add SEO Integration

vue

<script setup lang="ts">
import { useTextContent, useSEO } from '@duffcloudservices/cms'

const { t } = useTextContent({
  pageSlug: 'home',
  defaults: { /* ... */ }
})

// Apply SEO meta tags
const { applyHead } = useSEO('home')
applyHead()
</script>

Step 4: Register Pages

Create .dcs/pages.yaml:

yaml

pages:
  - slug: home
    path: /
    type: static
    title: Home
    deletable: false
    textKeys: []

  - slug: about
    path: /about
    type: static
    title: About Us
    deletable: true
    textKeys: []

  - slug: services
    path: /services
    type: static
    title: Services
    deletable: true
    textKeys: []

  - slug: contact
    path: /contact
    type: static
    title: Contact
    deletable: true
    textKeys: []

  - slug: blogs
    path: /blog
    type: index
    title: Blog
    deletable: false
    textKeys: []

Page Types

Type	Use Case	Notes
`static`	Regular pages	User-editable content
`index`	Collection pages	Blog index, etc.
`dynamic`	Generated pages	Auto-created content

Step 5: Set Up GitHub Integration

Add Repository Secrets

In GitHub Settings → Secrets and variables → Actions:

AZURE_CLIENT_ID=<service-principal-id>
AZURE_CLIENT_SECRET=<service-principal-secret>
AZURE_TENANT_ID=<azure-tenant-id>
AZURE_SUBSCRIPTION_ID=<subscription-id>
DCS_SERVER_URL=https://portal.duffcloudservices.com

Add Copilot Instructions

Create .github/copilot-instructions.md:

markdown

# Copilot Instructions for [Site Name]

## Project Overview
This is a VitePress marketing site integrated with DCS.

## Text Content
Use the `useTextContent` composable for all user-editable text:
\`\`\`vue
const { t } = useTextContent()
// t('key', 'default value')
\`\`\`

## Development Guidelines
- Follow Vue 3 Composition API patterns
- Use Tailwind CSS for styling
- Test changes in dev environment before production

Add Deployment Workflow

Create .github/workflows/draft-release-deploy.yml:

yaml

name: Draft Release Deploy

on:
  issues:
    types: [labeled]

jobs:
  deploy-draft:
    if: github.event.label.name == 'draft-release'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '22'
          
      - name: Install pnpm
        uses: pnpm/action-setup@v2
        with:
          version: 9
          
      - name: Install dependencies
        run: pnpm install
        
      - name: Build
        run: pnpm build
        
      - name: Deploy to Azure
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_SWA_TOKEN }}
          action: 'upload'
          app_location: '.vitepress/dist'

Step 6: Create Azure Resources

Static Web App (Development)

bash

az staticwebapp create \
  --name customer-site-dev \
  --resource-group dcs-sites-rg \
  --location eastus2 \
  --sku Free

Static Web App (Production)

bash

az staticwebapp create \
  --name customer-site-prod \
  --resource-group dcs-sites-rg \
  --location eastus2 \
  --sku Standard

Configure Custom Domain (Production)

bash

az staticwebapp hostname set \
  --name customer-site-prod \
  --hostname www.customer-site.com

Step 7: Register in DCS Portal

Create Site Record

Log into the DCS admin portal
Navigate to Sites → Add Site
Fill in site details:
- Slug: customer-site
- Name: Customer Site Name
- GitHub Repo: owner/customer-site
- Dev SWA Resource ID: (from Azure)
- Prod SWA Resource ID: (from Azure)

Assign to Company

Navigate to Companies → Select Company
Add site to company
Set appropriate user permissions

Step 8: Verify Integration

Validate Configuration

bash

dcs validate

Test Text Overrides

Create a test override in the portal
Verify it appears on the dev site
Delete the test override

Test Development Requests

Submit a test request
Verify GitHub issue is created
Verify Copilot response
Review and close test request

Onboarding Checklist

[ ] CLI installed and authenticated (dcs login)
[ ] Site initialized with dcs init
[ ] @duffcloudservices/cms package installed
[ ] Vite plugins configured
[ ] Text content composable implemented in pages
[ ] Pages registered in .dcs/pages.yaml
[ ] GitHub secrets configured
[ ] Deployment workflows added
[ ] Azure SWA resources created
[ ] Site registered in DCS portal
[ ] Configuration validated (dcs validate)
[ ] Integration tested end-to-end
[ ] Site owner trained on portal usage

Troubleshooting

Text overrides not appearing

Check API endpoint in configuration
Verify CORS settings on DCS server
Check browser console for errors

Deployment failing

Verify GitHub secrets are correct
Check Azure SWA resource IDs
Review workflow logs

GitHub integration issues

Verify webhook configuration
Check service principal permissions
Review DCS server logs

Next Steps

CMS Package Documentation — Full API reference
CLI Package Documentation — All commands and options
Site Configuration — Advanced configuration options
Release Management — Managing deployments
Portal Guide — Train site owners

Onboarding a New Site ​

Prerequisites ​

Quick Start (Recommended) ​

Step 1: Initialize DCS Configuration ​

Using the CLI (Recommended) ​

Manual Setup (Alternative) ​

Step 2: Install & Configure the CMS Package ​

Install Dependencies ​

Configure Vite Plugins ​

Add Environment Variables ​

Step 3: Implement Text Content Integration ​

Use the Composable ​

Add SEO Integration ​

Step 4: Register Pages ​

Page Types ​

Step 5: Set Up GitHub Integration ​

Add Repository Secrets ​

Add Copilot Instructions ​

Add Deployment Workflow ​

Step 6: Create Azure Resources ​

Static Web App (Development) ​

Static Web App (Production) ​

Configure Custom Domain (Production) ​

Step 7: Register in DCS Portal ​

Create Site Record ​

Assign to Company ​

Step 8: Verify Integration ​

Validate Configuration ​

Test Text Overrides ​

Test Development Requests ​

Onboarding Checklist ​

Troubleshooting ​

Text overrides not appearing ​

Deployment failing ​

GitHub integration issues ​

Next Steps ​

Onboarding a New Site

Prerequisites

Quick Start (Recommended)

Step 1: Initialize DCS Configuration

Using the CLI (Recommended)

Manual Setup (Alternative)

Step 2: Install & Configure the CMS Package

Install Dependencies

Configure Vite Plugins

Add Environment Variables

Step 3: Implement Text Content Integration

Use the Composable

Add SEO Integration

Step 4: Register Pages

Page Types

Step 5: Set Up GitHub Integration

Add Repository Secrets

Add Copilot Instructions

Add Deployment Workflow

Step 6: Create Azure Resources

Static Web App (Development)

Static Web App (Production)

Configure Custom Domain (Production)

Step 7: Register in DCS Portal

Create Site Record

Assign to Company

Step 8: Verify Integration

Validate Configuration

Test Text Overrides

Test Development Requests

Onboarding Checklist

Troubleshooting

Text overrides not appearing

Deployment failing

GitHub integration issues

Next Steps