# Self-service setup

> Create a new Fern docs site using the guided self-service workflow in the Dashboard.

The [self-service workflow](https://dashboard.buildwithfern.com/get-started) guides you through creating a new Fern Docs site in a few steps. If you're looking for an existing site you've already set up, [search for your organization](https://dashboard.buildwithfern.com/get-started/search) instead.

<Note>
  Prefer to set things up manually using the CLI? See the [Quickstart](/learn/docs/getting-started/quickstart) instead.
</Note>

## What gets created

When you complete the self-service workflow, Fern publishes your documentation to a brand-new site and creates a GitHub repository containing your site configuration (`docs.yml`), Markdown pages, and any API specifications. Your repo includes a `CLAUDE.md` file pre-populated with Fern documentation in [llms-full.txt format](/learn/docs/ai/llms-txt), giving AI coding assistants context for working with Fern.

The setup process also creates and configures:

* **Organization**: An organization using your org ID, with you as a member.
* **Fern token**: A `FERN_TOKEN` in your repository's GitHub secrets that authenticates the [Fern CLI](/learn/cli-api-reference/cli-reference/overview) in your CI/CD workflows, scoped to your organization.
* **GitHub Action**: A workflow that runs [`fern generate --docs`](/learn/cli-api-reference/cli-reference/commands#fern-generate---docs) whenever you push changes to your main branch, automatically rebuilding and publishing your documentation.

You can use the [Fern Dashboard](/learn/dashboard/getting-started/overview) to manage your GitHub repository connection, organization members, domains, and CLI version.

## Setup steps

<Steps>
  <Step title="Enter your organization name">
    Choose a unique identifier for your organization. This will be used in your docs URL and to identify your project in the Dashboard.

    <Frame>
      ![Enter organization name](https://files.buildwithfern.com/fern.docs.buildwithfern.com/learn/11f9f4aa68ea4acb78949127cc05f1cef5caaa1bbb1b95c58c89bf1dc2846e22/products/docs/pages/getting-started/images/org-name.png)
    </Frame>
  </Step>

  <Step title="Upload your API spec (optional)">
    Upload an OpenAPI specification to generate API Reference documentation. You can skip this step if you don't have a spec or want to add one later.

    <Frame>
      ![Upload API spec](https://files.buildwithfern.com/fern.docs.buildwithfern.com/learn/eb0c7cb840711c96f8141fa9e396a9a69d87e0f2b59a1b18c7fcc3fe77fdc67c/products/docs/pages/getting-started/images/api-spec.png)
    </Frame>
  </Step>

  <Step title="Configure your branding">
    Enter an existing website URL (like your marketing site or blog) so Fern can automatically match your brand style. Alternatively, pick a primary color and upload a logo manually.

    <Frame>
      ![Configure branding](https://files.buildwithfern.com/fern.docs.buildwithfern.com/learn/d7f102088aeca83cc9c60a97acd40a8f5d1cc2c950684994dd9a899d39f0d198/products/docs/pages/getting-started/images/marketing-site.png)
    </Frame>
  </Step>

  <Step title="Your site is live!">
    Fern publishes your documentation to a live URL you can visit immediately. You can also add your GitHub account as a collaborator to push changes and manage the repository, or head to the [Dashboard](/learn/dashboard/getting-started/overview) to manage your site settings.

    <Frame>
      ![Site published success screen](https://files.buildwithfern.com/fern.docs.buildwithfern.com/learn/57a57393cb56ab85054f51e49ce89b6aacbb84786b6a9e3cb76b9eb80ac27a89/products/docs/pages/getting-started/images/site-published.png)
    </Frame>
  </Step>
</Steps>

## Next steps

Start writing content and customizing your site:

<CardGroup cols={3}>
  <Card title="How Fern Docs work" icon="regular circle-info" href="/learn/docs/getting-started/how-it-works">
    Understand the content and deployment workflows powering your site.
  </Card>

  <Card title="Write your docs" icon="regular pen-to-square" href="/learn/docs/writing-content/markdown-basics">
    Learn Markdown basics and use components to create rich documentation.
  </Card>

  <Card title="Configure your site" icon="regular sliders" href="/learn/docs/configuration/site-level-settings">
    Set colors, typography, navigation, and more in your `docs.yml` file.
  </Card>
</CardGroup>

## Monitoring builds

Your documentation rebuilds automatically whenever you push changes to your main branch. To check the status of a build, go to the **Actions** tab in your GitHub repository. Each workflow run shows whether the build succeeded, along with any errors or warnings.

### Troubleshooting

<AccordionGroup>
  <Accordion title="Fern token issues">
    If your documentation build fails with an authentication error, the `FERN_TOKEN` may not be set correctly. To resolve this:

    1. Install the Fern CLI if you haven't already:
       ```bash
       npm install -g fern-api
       ```

    2. Add yourself as a collaborator to the repository if needed, then clone it locally.

    3. Run the following command from within your Fern project directory to generate a new token:
       ```bash
       fern token
       ```
       This generates a token scoped to your organization (as defined in `fern.config.json`).

    4. Copy the token and add it as a [repository secret](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository) named `FERN_TOKEN`.

    5. Go to the **Actions** tab in your repository and re-run the failed workflow.
  </Accordion>

  <Accordion title="API spec errors">
    If your build fails due to issues parsing your API specification, you can troubleshoot locally:

    1. Clone your documentation repository locally if you haven't already.

    2. Install the Fern CLI:
       ```bash
       npm install -g fern-api
       ```

    3. Run the following command to see detailed validation errors with line numbers:
       ```bash
       fern check --from-openapi
       ```
       This command prints validation errors directly from your OpenAPI specification, including the line numbers where the errors originate.

    Once you've resolved the errors in your API spec, commit and push the changes to trigger a new build.
  </Accordion>
</AccordionGroup>