How to Validate Your CircleCI Server Installation with Realitycheck

Introduction

Realitycheck is a testing repository that validates your CircleCI Server installation. Use this tool to verify that core features, such as workflows, environment variables, and resource classes, are functioning correctly after installing or updating CircleCI Server.

Prerequisites

Before starting, ensure you have:

• A CircleCI Server installation
• Permission to fork repositories in GitHub or GitHub Enterprise
• Admin access to create environment variables in your CircleCI projects
• Ability to generate a personal API token

Instructions

Step 1: Fork the Realitycheck Repository

For GitHub.com:

Go to the realitycheck repository and click "Fork" to copy it to your organization.

For GitHub Enterprise:

Create an empty repository in GitHub Enterprise, then run these commands:

git clone <your-new-ghe-repo-url>
cd <your-repo-name>
git pull git@github.com:circleci/realitycheck.git
git remote set-url origin <your-ghe-repo-url>
git push

Step 2: Add the Project to CircleCI Server

1. Log in to your CircleCI Server dashboard
2. Navigate to "Projects"
3. Find your forked realitycheck repository
4. Click "Set Up Project"

Step 3: Configure Environment Variables

Navigate to Project Settings > Environment Variables and add these two required variables:

• CIRCLE_TOKEN:
  - Generate a personal API token at `<your-server-url>/account/api`
  - Add the token value as `CIRCLE_TOKEN`
• CIRCLE_HOSTNAME:
  - Enter your server's base URL in this format: `https://server.example.com`
  - Remove any trailing slashes or "app" subdomains from the URL

Step 4: Trigger the Validation Build

Run this command to trigger a build:

git commit --allow-empty -m "Test realitycheck" && git push

Outcome

Once the build is complete, you will see three parallel workflows running in your CircleCI Server dashboard. If all workflows pass with green checkmarks, your CircleCI Server installation is configured correctly and ready for use.

If any workflows fail, review the build logs to identify which features need configuration adjustments. The workflows test resource class functionality, environment variable handling, and basic CircleCI features.

Additional Resources

• Realitycheck Repository - Complete testing details and feature descriptions
• CircleCI Server Documentation - Installation and configuration guides
• Managing API Tokens - How to create and manage tokens