Merge pull request #211 from signalwire/Devon/self-hosting

Devon-White · web-flow · commit eca10b79d2b1 · 2026-03-15T19:23:06.000-04:00
Self hosting setup
diff --git a/Dockerfile b/Dockerfile
@@ -0,0 +1,16 @@
+FROM fernenterprise/fern-self-hosted:0.112.5
+
+# Copy project files
+COPY package.json yarn.lock ./
+COPY fern/ /fern/
+COPY specs/ /specs/
+
+# Install yarn and dependencies
+RUN npm install -g yarn
+RUN yarn install --frozen-lockfile
+
+# Build all TypeSpec specs → OpenAPI YAML + SWML JSON Schema (outputs into /fern/apis/*)
+RUN yarn build:specs
+
+# Generate docs
+RUN fern-generate
diff --git a/docker-compose.yml b/docker-compose.yml
@@ -0,0 +1,7 @@
+services:
+  docs:
+    build: .
+    ports:
+      - "3000:3000"
+    environment:
+      - WARMUP=true
diff --git a/fern/fern.config.json b/fern/fern.config.json
@@ -1,4 +1,4 @@
 {
   "organization": "signalwire",
-  "version": "4.22.0"
+  "version": "4.29.0"
 }
diff --git a/fern/products/apis/pages/core/overview.mdx b/fern/products/apis/pages/core/overview.mdx
@@ -6,9 +6,9 @@ slug: /
 
 Welcome to SignalWire's REST API. Our REST API is a set of endpoints that make interacting with SignalWire simple and familiar.
 
-The REST API is structured like most other [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer) APIs: we use predictable and clear resource-oriented URLs that utilize built-in HTTP features like authentication, verbs, and error codes. This enables you to easily use any HTTP client in any language to make requests.
+The REST API is structured like most other [REST](https://en.wikipedia.org/wiki/REST) APIs: we use predictable and clear resource-oriented URLs that utilize built-in HTTP features like authentication, verbs, and error codes. This enables you to easily use any HTTP client in any language to make requests.
 
-Proper HTTP status codes and [JSON](http://www.json.org/) are returned in all REST API endpoints, including errors.
+Proper HTTP status codes and [JSON](https://www.json.org/json-en.html) are returned in all REST API endpoints, including errors.
 
 <CardGroup cols={3}>
 <Card title="Postman collection" icon="brands github" href="https://github.com/signalwire/rest-apis">
diff --git a/fern/products/compatibility-api/pages/cxml/guides/webhooks/common-webhook-errors.mdx b/fern/products/compatibility-api/pages/cxml/guides/webhooks/common-webhook-errors.mdx
@@ -55,7 +55,7 @@ If you see a 502 Bad Gateway error, this may mean that SignalWire's internal ser
 1. Confirm that the URL that you used is not protected by any HTTP Authentication, making it impossible for SignalWire to reach it.
 2. Double check to make sure that your web server is up, responsive, and publicly accessible.
 3. Make sure your web server allows HTTP POST requests to static resources (if the URL refers to .xml or .html files)
-4. Check the ping times and packet loss between your web server and www.signalwire.com
+4. Check the ping times and packet loss between your web server and `https://www.signalwire.com`
 
 ## XML response body exceeds size limit (error code 11750)
 
diff --git a/fern/products/platform/pages/platform/setup/api-credentials.mdx b/fern/products/platform/pages/platform/setup/api-credentials.mdx
@@ -12,7 +12,7 @@ The API credentials found on this page are your key to accessing SignalWire's AP
 </Frame>
 
 Most SignalWire API endpoints require authentication using 
-[HTTP Basic Auth](http://en.wikipedia.org/wiki/Basic_access_authentication). 
+[HTTP Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication). 
 HTTP Basic Authentication requires you to send an Authorization header with your Project ID and API Token. 
 
 Each project has its own Project ID and API Authentication Tokens you will need to use when making a request to the API. 
diff --git a/fern/products/swml/pages/get-started/index.mdx b/fern/products/swml/pages/get-started/index.mdx
@@ -72,7 +72,7 @@ sections:
     Accepts an array of [SWML methods](/docs/swml/reference).
   </ParamField>
   <ParamField path="*" type="object[]" optional>
-    Additional user-defined sections, invoked from `main` using [program flow control methods](/docs/swml/guides/goto-execute-transfer-disambiguation-cache-test).
+    Additional user-defined sections, invoked from `main` using [program flow control methods](/docs/swml/guides/goto-execute-transfer-disambiguation).
     
     User-defined sections can use any text string as the property. Like `main`, user-defined sections accept an array of [SWML methods](/docs/swml/reference).
   </ParamField>
diff --git a/fern/products/swml/pages/guides/basics/goto-execute-transfer.mdx b/fern/products/swml/pages/guides/basics/goto-execute-transfer.mdx
@@ -2,7 +2,7 @@
 id: 96578205-400a-41f1-9199-7500495236e4
 title: Control program flow
 subtitle: How are the methods goto, execute and transfer different?
-slug: /guides/goto-execute-transfer-disambiguation-cache-test
+slug: /guides/goto-execute-transfer-disambiguation
 description: Learn how to use the goto, execute, and transfer methods in SWML.
 ---
 
diff --git a/fern/products/swml/pages/reference/schema.mdx b/fern/products/swml/pages/reference/schema.mdx
diff --git a/fern/products/swml/swml.yml b/fern/products/swml/swml.yml
@@ -19,8 +19,8 @@ navigation:
     - page: Variables
       path: ./pages/reference/variables.mdx
   
-  #  - page: Schema
-   #   path: ./pages/reference/schema.mdx
+    - page: Schema
+      path: ./pages/reference/schema.mdx
   - folder: ./pages/reference/methods
     title-source: frontmatter
     title: Methods
diff --git a/scripts/check-links.js b/scripts/check-links.js
@@ -338,6 +338,8 @@ function runLychee(urls, options = {}) {
     noProgress = false,
     concurrency,
     label = 'links',
+    remap,
+    allowHttp = false,
   } = options;
 
   if (urls.length === 0) {
@@ -365,6 +367,14 @@ function runLychee(urls, options = {}) {
     args.push('--max-concurrency', String(concurrency));
   }
 
+  if (remap) {
+    args.push('--remap', remap);
+  }
+
+  if (allowHttp) {
+    args.push('--scheme', 'https', '--scheme', 'http', '--insecure');
+  }
+
   if (noProgress) {
     args.push('--no-progress');
   }
@@ -708,19 +718,28 @@ async function main() {
   let skipHttp = false;
   let noProgress = false;
   let outputFile = null;
+  let remap = null;
+  let concurrency = null;
+  let local = null;
 
   for (let i = 0; i < args.length; i++) {
     if (args[i] === '--sitemap' && args[i + 1]) sitemapUrl = args[++i];
     if (args[i] === '--skip-github') skipGithub = true;
     if (args[i] === '--skip-http') skipHttp = true;
     if (args[i] === '--no-progress') noProgress = true;
     if (args[i] === '--output' && args[i + 1]) outputFile = args[++i];
+    if (args[i] === '--remap' && args[i + 1]) remap = args[++i];
+    if (args[i] === '--concurrency' && args[i + 1]) concurrency = parseInt(args[++i], 10);
+    if (args[i] === '--local' && args[i + 1]) local = parseInt(args[++i], 10);
     if (args[i] === '-h' || args[i] === '--help') {
       console.log(`
 Usage: node scripts/check-links.js --sitemap <url> [options]
 
 Options:
   --sitemap <url>   Sitemap URL to check (required)
+  --local <port>    Check against localhost on the given port (auto-remaps and sets sitemap)
+  --remap <mapping> Remap URLs before checking (e.g. "https://old.com https://new.com")
+  --concurrency <n> Max concurrent requests for lychee (default: from lychee.toml)
   --skip-github     Skip GitHub URL verification (both local and HTTP)
   --skip-http       Skip all HTTP link checking (lychee)
   --no-progress     Disable progress output (for CI)
@@ -736,6 +755,12 @@ Examples:
   # Check a preview deployment
   node scripts/check-links.js --sitemap https://preview-xxx.docs.buildwithfern.com/sitemap.xml
 
+  # Check against local self-hosted container
+  node scripts/check-links.js --local 3000 --skip-github
+
+  # Check self-hosted docs via tunnel (remap production URLs to tunnel)
+  node scripts/check-links.js --sitemap https://tunnel.trycloudflare.com/docs/sitemap.xml --remap "https://signalwire.com/docs https://tunnel.trycloudflare.com/docs"
+
   # Quick check (skip GitHub for speed)
   node scripts/check-links.js --sitemap <url> --skip-github
 `);
@@ -746,6 +771,56 @@ Examples:
   log.header('Link Checker');
   log.newline();
 
+  // --local: auto-configure sitemap, remap, and scheme for localhost
+  if (local) {
+    const localBase = `http://localhost:${local}`;
+
+    // Read custom-domain from docs.yml to know what to remap from
+    const docsYmlPath = join(REPO_ROOT, 'fern', 'docs.yml');
+    let productionBase = null;
+    try {
+      const docsYml = readFileSync(docsYmlPath, 'utf8');
+      const domainMatch = docsYml.match(/custom-domain:\s*(.+)/);
+      if (domainMatch) {
+        productionBase = `https://${domainMatch[1].trim()}`;
+      }
+    } catch {
+      // Fall through
+    }
+
+    if (!productionBase) {
+      log.error('Could not read custom-domain from fern/docs.yml');
+      process.exit(1);
+    }
+
+    // Detect base path from sitemap
+    let basePath = '';
+    try {
+      // Try common paths
+      for (const tryPath of ['/docs/sitemap.xml', '/sitemap.xml']) {
+        const resp = await fetch(`${localBase}${tryPath}`);
+        if (resp.ok) {
+          sitemapUrl = `${localBase}${tryPath}`;
+          basePath = tryPath.replace('/sitemap.xml', '');
+          break;
+        }
+      }
+    } catch {
+      // Fall through
+    }
+
+    if (!sitemapUrl) {
+      log.error(`Could not find sitemap at ${localBase}. Is the container running?`);
+      process.exit(1);
+    }
+
+    remap = `${productionBase} ${localBase}${basePath}`;
+    log.info(`Local mode: port ${local}`);
+    log.info(`Sitemap: ${sitemapUrl}`);
+    log.info(`Remap: ${productionBase} → ${localBase}${basePath}`);
+    log.newline();
+  }
+
   // Sitemap URL is required
   if (!sitemapUrl) {
     log.error('Error: --sitemap <url> is required');
@@ -754,7 +829,17 @@ Examples:
   }
 
   // 1. Fetch sitemap URLs
-  const sitemapUrls = await fetchSitemap(sitemapUrl);
+  let sitemapUrls = await fetchSitemap(sitemapUrl);
+
+  // Remap sitemap URLs if --remap is specified
+  if (remap) {
+    const [from, to] = remap.split(' ');
+    if (from && to) {
+      log.info(`Remapping URLs: ${from} → ${to}`);
+      sitemapUrls = sitemapUrls.map(url => url.replace(from, to));
+    }
+  }
+
   log.info(`Found ${sitemapUrls.length} URLs in sitemap`);
   log.debug(`Sample URLs: ${sitemapUrls.slice(0, 3).join(', ')}${sitemapUrls.length > 3 ? '...' : ''}`);
 
@@ -792,6 +877,9 @@ Examples:
     // Main lychee run - exclude GitHub entirely (handled separately)
     results.httpMain = runLychee(sitemapUrls, {
       noProgress,
+      remap,
+      concurrency,
+      allowHttp: !!local,
       label: 'non-GitHub links',
     });
 
@@ -800,6 +888,7 @@ Examples:
       log.newline();
       results.githubHttp = runLychee(githubUrls.httpCheck, {
         noProgress,
+        remap,
         concurrency: GITHUB_HTTP_CONCURRENCY,
         label: 'GitHub HTTP links',
       });

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`	`1`	`{`
`2`	`2`	`"organization": "signalwire",`
`3`		`- "version": "4.22.0"`
	`3`	`+ "version": "4.29.0"`
`4`	`4`	`}`