From 8f7dd03ddb9760478073b9989965c2a54f8507d2 Mon Sep 17 00:00:00 2001 From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com> Date: Mon, 5 Jan 2026 20:03:14 +0000 Subject: [PATCH 1/8] docs: add Setup section with --local flag and generators.yml configuration for self-hosted SDKs --- fern/products/sdks/guides/self-hosted.mdx | 60 +++++++++++++++++++++++ 1 file changed, 60 insertions(+) diff --git a/fern/products/sdks/guides/self-hosted.mdx b/fern/products/sdks/guides/self-hosted.mdx index a7664ae1c..4e7e47ca9 100644 --- a/fern/products/sdks/guides/self-hosted.mdx +++ b/fern/products/sdks/guides/self-hosted.mdx @@ -8,6 +8,66 @@ description: Fern supports self-hosting SDK generation so that you can run SDK g Fern SDK generation [runs on Fern's infrastructure by default](/sdks/overview/how-it-works). Self-hosting allows you to run SDK generation on your own infrastructure to meet specific security or compliance requirements. +## Setup + +To run SDK generation locally, use the `--local` flag with the `fern generate` command. This downloads and runs the SDK generator Docker containers on your own machine instead of using Fern's cloud infrastructure. + +```bash +fern generate --local +``` + +You can combine `--local` with other flags like `--group` to generate specific SDKs: + +```bash +fern generate --group python-sdk --local +``` + +### Configure output location + +For self-hosted generation, configure your `generators.yml` to output SDKs to your local file system or a GitHub repository you control. + + + + +Output generated SDKs directly to a local directory: + +```yaml title="generators.yml" +groups: + python-sdk: + generators: + - name: fernapi/fern-python-sdk + version: 4.0.0 + output: + location: local-file-system + path: ../sdks/python +``` + + + + +Push generated SDKs to your own GitHub repository. Configure the `github` property with your repository details: + +```yaml title="generators.yml" +groups: + python-sdk: + generators: + - name: fernapi/fern-python-sdk + version: 4.0.0 + github: + repository: your-org/python-sdk + mode: push + branch: main +``` + +For more details on GitHub publishing modes (`release`, `pull-request`, `push`), see the [generators.yml reference](/learn/sdks/reference/generators-yml#github). + + + + + +Self-hosted SDK generation uses the Fern CLI with the `--local` flag. The self-hosted Docker image referenced in [self-hosted docs setup](/learn/docs/enterprise/self-hosted) is specifically for documentation generation, not SDK generation. + + ## When to use self-hosting Self-hosting is typically required for organizations that operate without internet access, have strict compliance requirements, or need full control over their SDK generation process. From 5ce1eddd7e72af2816d95f6a92fc78dd2ed5578b Mon Sep 17 00:00:00 2001 From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com> Date: Mon, 5 Jan 2026 20:07:07 +0000 Subject: [PATCH 2/8] docs: update self-hosted SDK github config to use GithubSelfhostedSchema with uri and token --- fern/products/sdks/guides/self-hosted.mdx | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/fern/products/sdks/guides/self-hosted.mdx b/fern/products/sdks/guides/self-hosted.mdx index 4e7e47ca9..f953b4a5e 100644 --- a/fern/products/sdks/guides/self-hosted.mdx +++ b/fern/products/sdks/guides/self-hosted.mdx @@ -45,7 +45,7 @@ groups: -Push generated SDKs to your own GitHub repository. Configure the `github` property with your repository details: +Push generated SDKs to your own GitHub repository. When using the `--local` flag, configure the `github` property with the self-hosted schema: ```yaml title="generators.yml" groups: @@ -54,20 +54,17 @@ groups: - name: fernapi/fern-python-sdk version: 4.0.0 github: - repository: your-org/python-sdk + uri: https://github.com/your-org/python-sdk + token: ${GITHUB_TOKEN} mode: push branch: main ``` -For more details on GitHub publishing modes (`release`, `pull-request`, `push`), see the [generators.yml reference](/learn/sdks/reference/generators-yml#github). +The self-hosted GitHub configuration uses `uri` and `token` properties instead of `repository`. The `mode` can be `push` or `pull-request`. - -Self-hosted SDK generation uses the Fern CLI with the `--local` flag. The self-hosted Docker image referenced in [self-hosted docs setup](/learn/docs/enterprise/self-hosted) is specifically for documentation generation, not SDK generation. - - ## When to use self-hosting Self-hosting is typically required for organizations that operate without internet access, have strict compliance requirements, or need full control over their SDK generation process. From 6c89d954b88b4736b1871142356d44e08332312d Mon Sep 17 00:00:00 2001 From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com> Date: Mon, 5 Jan 2026 20:12:24 +0000 Subject: [PATCH 3/8] docs: remove Docker image references from self-hosted SDK documentation --- fern/products/sdks/guides/self-hosted.mdx | 34 ++++++++++------------- 1 file changed, 14 insertions(+), 20 deletions(-) diff --git a/fern/products/sdks/guides/self-hosted.mdx b/fern/products/sdks/guides/self-hosted.mdx index f953b4a5e..7ef654896 100644 --- a/fern/products/sdks/guides/self-hosted.mdx +++ b/fern/products/sdks/guides/self-hosted.mdx @@ -10,7 +10,7 @@ Fern SDK generation [runs on Fern's infrastructure by default](/sdks/overview/ho ## Setup -To run SDK generation locally, use the `--local` flag with the `fern generate` command. This downloads and runs the SDK generator Docker containers on your own machine instead of using Fern's cloud infrastructure. +To run SDK generation locally, use the `--local` flag with the `fern generate` command. This runs SDK generation on your own machine instead of using Fern's cloud infrastructure. ```bash fern generate --local @@ -77,34 +77,28 @@ Unless you have specific requirements that prevent using Fern's default hosting, ## How it works -When you run `fern generate`, Fern uses Docker containers to execute SDK generation logic. By default, Fern runs **cloud generation** by allocating compute space and running the container remotely. With **self-hosted (local) generation**, you download and run the same Docker container on your own infrastructure. - -Both approaches generate partial SDK files to your configured output location, then Fern verifies your organization registration and completes the SDK by adding package distribution files. +When you run `fern generate --local`, the Fern CLI executes SDK generation on your local machine instead of using Fern's cloud infrastructure. The CLI handles downloading the necessary generator packages and running the generation process locally. The self-hosted process works as follows: -1. **Download the Docker image** - Fern provides the location of the most up-to-date Docker image containing the SDK generation logic -1. **Upload your fern folder** - Add your API definition and other configuration files to the container -1. **Run the container** - Execute SDK generation using standard Docker commands -1. **Partial SDK output** - Core SDK files are generated and saved to your configured output location (local file system, GitHub repository, package registry, etc.) +1. **Run the CLI** - Execute `fern generate --local` on your machine +1. **Generate SDK** - The Fern CLI generates SDK files based on your API definition and `generators.yml` configuration +1. **Output SDK** - Generated SDK files are saved to your configured output location (local file system or GitHub repository) 1. **Organization verification** - Fern verifies your organization registration and completes SDK generation by adding package distribution files like `pyproject.toml`, READMEs, and dependency configurations -1. **Receive updated Docker images** - Fern releases new versions of the Docker image that your team can evaluate and deploy when ready ### Architecture diagram ```mermaid sequenceDiagram autonumber - participant F as Fern participant C as Customer - participant S as Customer Server - F->>C: Provides Docker image - C->>S: Uploads fern folder - C->>S: Runs Docker command - S->>S: Output partial SDK - F->>F: Checks organization registration - F->>S: Completes SDK generation - F->>C: Releases updated Docker image - C->>C: Evaluates new version - C->>S: Deploys updated image + participant CLI as Fern CLI + participant F as Fern + participant O as Output (Local/GitHub) + C->>CLI: Runs fern generate --local + CLI->>CLI: Generates SDK files + CLI->>O: Outputs SDK to configured location + CLI->>F: Verifies organization + F->>CLI: Completes SDK with package files + CLI->>O: Outputs final SDK ``` From 1f3cc56026f3d0f55aec2c24a4356a7b4df75c8d Mon Sep 17 00:00:00 2001 From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com> Date: Mon, 5 Jan 2026 20:15:21 +0000 Subject: [PATCH 4/8] docs: update self-hosted SDK process flow with correct order, Docker requirement, and network call details --- fern/products/sdks/guides/self-hosted.mdx | 31 +++++++++++++++++------ 1 file changed, 23 insertions(+), 8 deletions(-) diff --git a/fern/products/sdks/guides/self-hosted.mdx b/fern/products/sdks/guides/self-hosted.mdx index 7ef654896..e1fc8acc6 100644 --- a/fern/products/sdks/guides/self-hosted.mdx +++ b/fern/products/sdks/guides/self-hosted.mdx @@ -77,14 +77,27 @@ Unless you have specific requirements that prevent using Fern's default hosting, ## How it works -When you run `fern generate --local`, the Fern CLI executes SDK generation on your local machine instead of using Fern's cloud infrastructure. The CLI handles downloading the necessary generator packages and running the generation process locally. +When you run `fern generate --local`, the Fern CLI executes SDK generation on your local machine instead of using Fern's cloud infrastructure. + + +A Docker daemon must be running on the machine where you run the command, as SDK generation runs inside a Docker container. + The self-hosted process works as follows: -1. **Run the CLI** - Execute `fern generate --local` on your machine -1. **Generate SDK** - The Fern CLI generates SDK files based on your API definition and `generators.yml` configuration +1. **Organization verification** - The CLI verifies your organization registration with Fern +1. **Download generator image** - If not already cached, the CLI downloads the generator's Docker image +1. **Generate SDK** - The CLI runs the generator container locally to produce SDK files based on your API definition and `generators.yml` configuration 1. **Output SDK** - Generated SDK files are saved to your configured output location (local file system or GitHub repository) -1. **Organization verification** - Fern verifies your organization registration and completes SDK generation by adding package distribution files like `pyproject.toml`, READMEs, and dependency configurations + +### Network calls + +When using the `--local` flag, the Fern CLI makes only two network calls: + +1. **Organization verification** - Validates your Fern organization registration +1. **Docker image download** - Downloads the generator image if not already available locally + +No API definition or specification data is sent over the network. All SDK generation happens locally on your machine. ### Architecture diagram @@ -94,11 +107,13 @@ sequenceDiagram participant C as Customer participant CLI as Fern CLI participant F as Fern + participant D as Docker participant O as Output (Local/GitHub) C->>CLI: Runs fern generate --local - CLI->>CLI: Generates SDK files - CLI->>O: Outputs SDK to configured location CLI->>F: Verifies organization - F->>CLI: Completes SDK with package files - CLI->>O: Outputs final SDK + F->>CLI: Confirms registration + CLI->>F: Downloads generator image (if needed) + CLI->>D: Runs generator container + D->>D: Generates SDK files locally + D->>O: Outputs SDK to configured location ``` From 58c2c6d68c15521293f327fd9c6735f4e43e808d Mon Sep 17 00:00:00 2001 From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com> Date: Mon, 5 Jan 2026 20:21:24 +0000 Subject: [PATCH 5/8] docs: simplify architecture diagram with fewer participants and fix output flow --- fern/products/sdks/guides/self-hosted.mdx | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/fern/products/sdks/guides/self-hosted.mdx b/fern/products/sdks/guides/self-hosted.mdx index e1fc8acc6..1cd1ffbb1 100644 --- a/fern/products/sdks/guides/self-hosted.mdx +++ b/fern/products/sdks/guides/self-hosted.mdx @@ -107,13 +107,10 @@ sequenceDiagram participant C as Customer participant CLI as Fern CLI participant F as Fern - participant D as Docker - participant O as Output (Local/GitHub) - C->>CLI: Runs fern generate --local - CLI->>F: Verifies organization - F->>CLI: Confirms registration - CLI->>F: Downloads generator image (if needed) - CLI->>D: Runs generator container - D->>D: Generates SDK files locally - D->>O: Outputs SDK to configured location + C->>CLI: fern generate --local + CLI->>F: Verify org + F->>CLI: OK + CLI->>F: Pull image (if needed) + CLI->>CLI: Run container, generate SDK + CLI->>CLI: Push to output (local/GitHub) ``` From ceb05648dc3644082d288b1abee14a96824a1cf7 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Mon, 5 Jan 2026 15:53:56 -0500 Subject: [PATCH 6/8] restructure info, add steps --- fern/products/sdks/guides/self-hosted.mdx | 124 ++++++++++++---------- 1 file changed, 67 insertions(+), 57 deletions(-) diff --git a/fern/products/sdks/guides/self-hosted.mdx b/fern/products/sdks/guides/self-hosted.mdx index 1cd1ffbb1..d29abd49d 100644 --- a/fern/products/sdks/guides/self-hosted.mdx +++ b/fern/products/sdks/guides/self-hosted.mdx @@ -6,32 +6,80 @@ description: Fern supports self-hosting SDK generation so that you can run SDK g -Fern SDK generation [runs on Fern's infrastructure by default](/sdks/overview/how-it-works). Self-hosting allows you to run SDK generation on your own infrastructure to meet specific security or compliance requirements. +Fern SDK generation [runs on Fern's infrastructure by default](/sdks/overview/how-it-works). Self-hosting allows you to run SDK generation on your own infrastructure. Use self-hosting if your organization: + +- Operates without internet access +- Has strict compliance or security requirements +- Needs full control over your SDK generation process + +When you self-host, you're responsible for infrastructure management and SDK distribution. Self-hosted SDK generation includes [all Fern SDK features](/learn/sdks/overview/capabilities). + + +Unless you have specific requirements that prevent using Fern's default hosting, we recommend **using our managed cloud generation solution** for easier setup and maintenance. + + +## How it works + +When you run `fern generate --local`, the Fern CLI executes SDK generation on your local machine instead of using Fern's cloud infrastructure. The self-hosted process works as follows: + +1. **Organization verification** (network call) - The CLI verifies your organization registration with Fern +1. **Download generator image** (network call if not cached) - The CLI downloads the generator's Docker image if not already available locally +1. **Generate SDK** (local) - The CLI runs the generator container locally to produce SDK files based on your API definition and `generators.yml` configuration +1. **Output SDK** (local) - Generated SDK files are saved to your configured output location (local file system or GitHub repository) + +These are the only network calls made when using the `--local` flag. No API definition or specification data is sent over the network: all SDK generation happens locally on your machine. + + + +```mermaid +sequenceDiagram + autonumber + participant C as Customer + participant CLI as Fern CLI + participant F as Fern + C->>CLI: fern generate --local + CLI->>F: Verify org + F->>CLI: OK + CLI->>F: Pull image (if needed) + CLI->>CLI: Run container, generate SDK + CLI->>CLI: Push to output (local/GitHub) +``` + + ## Setup -To run SDK generation locally, use the `--local` flag with the `fern generate` command. This runs SDK generation on your own machine instead of using Fern's cloud infrastructure. + + + +Verify that a Docker daemon is running on your machine, as SDK generation runs inside a Docker container: ```bash -fern generate --local +docker ps ``` -You can combine `--local` with other flags like `--group` to generate specific SDKs: + + + + +Generate a `FERN_TOKEN` variable in your local environment (required for local generation): ```bash -fern generate --group python-sdk --local +fern token ``` -### Configure output location + + + -For self-hosted generation, configure your `generators.yml` to output SDKs to your local file system or a GitHub repository you control. +Configure your `generators.yml` to output SDKs to your local file system or a GitHub repository you control. Output generated SDKs directly to a local directory: -```yaml title="generators.yml" +```yaml title="generators.yml" {7-8} groups: python-sdk: generators: @@ -45,9 +93,9 @@ groups: -Push generated SDKs to your own GitHub repository. When using the `--local` flag, configure the `github` property with the self-hosted schema: +To push generated SDKs to your GitHub repository, configure the `github` property with `uri` and `token`. Set the [publishing `mode`](/learn/sdks/reference/generators-yml#github) to `push` for direct commits or `pull-request` to create PRs. -```yaml title="generators.yml" +```yaml title="generators.yml" {7-8} groups: python-sdk: generators: @@ -60,57 +108,19 @@ groups: branch: main ``` -The self-hosted GitHub configuration uses `uri` and `token` properties instead of `repository`. The `mode` can be `push` or `pull-request`. - + + -## When to use self-hosting - -Self-hosting is typically required for organizations that operate without internet access, have strict compliance requirements, or need full control over their SDK generation process. - -When you self-host, you're responsible for server setup, security, maintenance, and deciding how to distribute your generated SDKs. Self-hosted SDK generation includes [all Fern SDK features](/learn/sdks/overview/capabilities). - - -Unless you have specific requirements that prevent using Fern's default hosting, we recommend **using our managed cloud generation solution** for easier setup and maintenance. - - -## How it works - -When you run `fern generate --local`, the Fern CLI executes SDK generation on your local machine instead of using Fern's cloud infrastructure. +Use the `--local` flag to generate SDKs locally instead of using Fern's cloud infrastructure. You can combine `--local` with other flags like `--group` to generate specific SDKs locally. - -A Docker daemon must be running on the machine where you run the command, as SDK generation runs inside a Docker container. - - -The self-hosted process works as follows: - -1. **Organization verification** - The CLI verifies your organization registration with Fern -1. **Download generator image** - If not already cached, the CLI downloads the generator's Docker image -1. **Generate SDK** - The CLI runs the generator container locally to produce SDK files based on your API definition and `generators.yml` configuration -1. **Output SDK** - Generated SDK files are saved to your configured output location (local file system or GitHub repository) - -### Network calls - -When using the `--local` flag, the Fern CLI makes only two network calls: - -1. **Organization verification** - Validates your Fern organization registration -1. **Docker image download** - Downloads the generator image if not already available locally +```bash +fern generate --local +fern generate --group python-sdk --local +``` -No API definition or specification data is sent over the network. All SDK generation happens locally on your machine. + + -### Architecture diagram -```mermaid -sequenceDiagram - autonumber - participant C as Customer - participant CLI as Fern CLI - participant F as Fern - C->>CLI: fern generate --local - CLI->>F: Verify org - F->>CLI: OK - CLI->>F: Pull image (if needed) - CLI->>CLI: Run container, generate SDK - CLI->>CLI: Push to output (local/GitHub) -``` From 738807864cf2dae024e96b45d376f191bc853d8b Mon Sep 17 00:00:00 2001 From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com> Date: Mon, 5 Jan 2026 20:56:52 +0000 Subject: [PATCH 7/8] docs: add --local flag to CLI reference and self-hosted GitHub config to generators.yml reference --- .../cli-api-reference/pages/commands.mdx | 18 ++++++++- .../reference/generators-yml-reference.mdx | 39 +++++++++++++++++-- 2 files changed, 52 insertions(+), 5 deletions(-) diff --git a/fern/products/cli-api-reference/pages/commands.mdx b/fern/products/cli-api-reference/pages/commands.mdx index 2cb514fba..cd29c7954 100644 --- a/fern/products/cli-api-reference/pages/commands.mdx +++ b/fern/products/cli-api-reference/pages/commands.mdx @@ -180,7 +180,7 @@ hideOnThisPage: true ```bash - fern generate [--group ] [--api ] [--version ] [--preview] [--fernignore ] + fern generate [--group ] [--api ] [--version ] [--preview] [--fernignore ] [--local] ``` @@ -246,6 +246,22 @@ hideOnThisPage: true fern generate --fernignore ./custom-fernignore ``` + ### local + + Use `--local` to run SDK generation on your own machine instead of using Fern's cloud infrastructure. This is useful for organizations with strict security or compliance requirements. See [self-hosted SDKs](/learn/sdks/deep-dives/self-hosted) for setup instructions. + + ```bash + # Generate all SDKs locally + fern generate --local + + # Generate specific SDK group locally + fern generate --group python-sdk --local + ``` + + + A Docker daemon must be running on your machine, as SDK generation runs inside a Docker container. + + diff --git a/fern/products/sdks/reference/generators-yml-reference.mdx b/fern/products/sdks/reference/generators-yml-reference.mdx index 7ae8d9563..dae11dfc1 100644 --- a/fern/products/sdks/reference/generators-yml-reference.mdx +++ b/fern/products/sdks/reference/generators-yml-reference.mdx @@ -737,11 +737,9 @@ Local directory path where generated files will be saved #### `github` Specify how your SDKs are generated in GitHub using the `github` configuration. -Designate the `mode` to specifiy how Fern handles your code changes. For all of the -modes, you must specify the GitHub repository in which you want to store your -SDK code. You can also configure a branch name, license, and reviewers. +Designate the `mode` to specify how Fern handles your code changes. For cloud generation, specify the GitHub repository using `repository`. For [self-hosted generation](/learn/sdks/deep-dives/self-hosted), use `uri` and `token` instead. -Make sure the [Fern GitHub app](https://github.com/apps/fern-api) is installed on your destination repository +Make sure the [Fern GitHub app](https://github.com/apps/fern-api) is installed on your destination repository (not required for self-hosted generation) @@ -846,6 +844,39 @@ Software license for the generated SDK. Specify which teams and users should review generated code. See [reviewers configuration](#reviewers-1). + + +For [self-hosted SDK generation](/learn/sdks/deep-dives/self-hosted), use the `--local` flag with `fern generate` and configure the `github` property with `uri` and `token` instead of `repository`. + +```yml {6-10} +groups: + ts-sdk: + generators: + - name: fernapi/fern-typescript-sdk + ... + github: + uri: "https://github.com/your-org/your-repo-name" + token: "${GITHUB_TOKEN}" + mode: "push" + branch: "main" +``` + + +Full URL to your GitHub repository (e.g., `https://github.com/your-org/your-repo`). + + + +GitHub Personal Access Token with repository write permissions. Use an environment variable reference (e.g., `${GITHUB_TOKEN}`). + + + +How to publish changes: `push` commits directly to the branch, `pull-request` opens a PR for review. + + + +Target branch for commits or pull requests. + + #### `metadata` From d2dd1bdcf72f47f2626d480facca10059b6fc066 Mon Sep 17 00:00:00 2001 From: Devin Logan Date: Mon, 5 Jan 2026 20:00:26 -0500 Subject: [PATCH 8/8] further clarify steps --- .../cli-api-reference/pages/commands.mdx | 5 + fern/products/sdks/guides/self-hosted.mdx | 100 ++++++++++++------ .../reference/generators-yml-reference.mdx | 2 +- 3 files changed, 73 insertions(+), 34 deletions(-) diff --git a/fern/products/cli-api-reference/pages/commands.mdx b/fern/products/cli-api-reference/pages/commands.mdx index cd29c7954..581b0964f 100644 --- a/fern/products/cli-api-reference/pages/commands.mdx +++ b/fern/products/cli-api-reference/pages/commands.mdx @@ -197,10 +197,15 @@ hideOnThisPage: true # Run all groups defined in the "frontend" alias fern generate --group frontend + + # Run a specific group locally (self-hosted) + fern generate --group python-sdk --local ``` You can also set an alias as your `default-group` in `generators.yml`, so running `fern generate` without any arguments will run all groups in that alias. + The `--group` flag can be combined with other flags like `--local` for [self-hosted SDK generation](/learn/sdks/deep-dives/self-hosted), `--preview` for local testing, or `--version` to specify the SDK version. + ### preview Use `--preview` to test SDK changes locally before publishing. This is especially useful during development: diff --git a/fern/products/sdks/guides/self-hosted.mdx b/fern/products/sdks/guides/self-hosted.mdx index d29abd49d..4a50824b6 100644 --- a/fern/products/sdks/guides/self-hosted.mdx +++ b/fern/products/sdks/guides/self-hosted.mdx @@ -18,36 +18,16 @@ When you self-host, you're responsible for infrastructure management and SDK dis Unless you have specific requirements that prevent using Fern's default hosting, we recommend **using our managed cloud generation solution** for easier setup and maintenance. -## How it works - -When you run `fern generate --local`, the Fern CLI executes SDK generation on your local machine instead of using Fern's cloud infrastructure. The self-hosted process works as follows: - -1. **Organization verification** (network call) - The CLI verifies your organization registration with Fern -1. **Download generator image** (network call if not cached) - The CLI downloads the generator's Docker image if not already available locally -1. **Generate SDK** (local) - The CLI runs the generator container locally to produce SDK files based on your API definition and `generators.yml` configuration -1. **Output SDK** (local) - Generated SDK files are saved to your configured output location (local file system or GitHub repository) - -These are the only network calls made when using the `--local` flag. No API definition or specification data is sent over the network: all SDK generation happens locally on your machine. - - +## Setup -```mermaid -sequenceDiagram - autonumber - participant C as Customer - participant CLI as Fern CLI - participant F as Fern - C->>CLI: fern generate --local - CLI->>F: Verify org - F->>CLI: OK - CLI->>F: Pull image (if needed) - CLI->>CLI: Run container, generate SDK - CLI->>CLI: Push to output (local/GitHub) -``` + +This page assumes that you have: - +* An initialized `fern` folder. See [Set up the `fern` folder](/sdks/overview/quickstart). +* SDK generators configured in `generators.yml`. See language-specific quickstarts: [TypeScript](/sdks/generators/typescript/quickstart), [Python](/sdks/generators/python/quickstart), [Go](/sdks/generators/go/quickstart), [Java](/sdks/generators/java/quickstart), etc. + -## Setup +Self-hosted SDK generation allows you to output to your local file system or push directly to a GitHub repository you control. Follow these steps to set up and run local generation: @@ -60,14 +40,16 @@ docker ps - + -Generate a `FERN_TOKEN` variable in your local environment (required for local generation): +Generate a Fern token, which is required for local generation to verify your organization. ```bash fern token ``` +The token is specific to your organization defined in `fern.config.json` and doesn't expire. + @@ -75,7 +57,7 @@ fern token Configure your `generators.yml` to output SDKs to your local file system or a GitHub repository you control. - + Output generated SDKs directly to a local directory: @@ -91,11 +73,11 @@ groups: ``` - + To push generated SDKs to your GitHub repository, configure the `github` property with `uri` and `token`. Set the [publishing `mode`](/learn/sdks/reference/generators-yml#github) to `push` for direct commits or `pull-request` to create PRs. -```yaml title="generators.yml" {7-8} +```yaml title="generators.yml" {4-8} groups: python-sdk: generators: @@ -111,9 +93,35 @@ groups: + + + +Configure authentication based on your chosen output location. + + + + +Set your Fern token as an environment variable: + +```bash +export FERN_TOKEN=your-generated-token +``` + + + + +Set up GitHub secrets for authentication. In your repository's **Settings** > **Secrets and variables** > **Actions**, add: + +- `FERN_TOKEN`: The token you generated above +- `GITHUB_TOKEN`: A [GitHub personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) with repository write access + + + + + -Use the `--local` flag to generate SDKs locally instead of using Fern's cloud infrastructure. You can combine `--local` with other flags like `--group` to generate specific SDKs locally. +Use the `--local` flag to generate SDKs locally instead of using Fern's cloud infrastructure. You can combine `--local` with `--group` to generate specific SDKs locally. ```bash fern generate --local @@ -123,4 +131,30 @@ fern generate --group python-sdk --local +## How it works + +When you run `fern generate --local`, the Fern CLI executes SDK generation on your local machine instead of using Fern's cloud infrastructure. The self-hosted process works as follows: + +1. **Organization verification** (network call) - The CLI verifies your organization registration with Fern +1. **Download generator image** (network call if not cached) - The CLI downloads the generator's Docker image if not already available locally +1. **Generate SDK** (local) - The CLI runs the generator container locally to produce SDK files based on your API definition and `generators.yml` configuration +1. **Output SDK** (local) - Generated SDK files are saved to your configured output location (local file system or GitHub repository) +These are the only network calls made when using the `--local` flag. No API definition or specification data is sent over the network: all SDK generation happens locally on your machine. + + + +```mermaid +sequenceDiagram + autonumber + participant C as Customer + participant CLI as Fern CLI + participant F as Fern + C->>CLI: fern generate --local + CLI->>F: Verify org + CLI->>F: Pull image (if needed) + CLI->>CLI: Run container, generate SDK + CLI->>CLI: Push to output (local/GitHub) +``` + + diff --git a/fern/products/sdks/reference/generators-yml-reference.mdx b/fern/products/sdks/reference/generators-yml-reference.mdx index dae11dfc1..1b3945761 100644 --- a/fern/products/sdks/reference/generators-yml-reference.mdx +++ b/fern/products/sdks/reference/generators-yml-reference.mdx @@ -846,7 +846,7 @@ Specify which teams and users should review generated code. See [reviewers confi -For [self-hosted SDK generation](/learn/sdks/deep-dives/self-hosted), use the `--local` flag with `fern generate` and configure the `github` property with `uri` and `token` instead of `repository`. +For [self-hosted SDK generation](/learn/sdks/deep-dives/self-hosted), configure the `github` property with `uri` and `token` instead of `repository`. ```yml {6-10} groups: