Skip to content

Commit fb20184

Browse files
jsbroksjsbroks
committed
clean up docs
1 parent 504b5f1 commit fb20184

10 files changed

+195
-123
lines changed

‎CLAUDE.md

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Ctrlplane Documentation Guidelines
2+
3+
## Project Information
4+
- Documentation platform: Mintlify
5+
- Primary content: MDX files for API documentation and concept guides
6+
7+
## Documentation Structure
8+
- API endpoints follow OpenAPI spec format with `---` frontmatter
9+
- Concept pages use descriptive titles and clear structure
10+
- Use tables for comparing capabilities
11+
- Group related documentation in directories by category
12+
13+
## Styling Guidelines
14+
- Frontmatter should include title and description
15+
- Use h2 (##) for main sections, h3 (###) for subsections
16+
- Tables should include clear headers with alignment (: syntax)
17+
- Components like `<CardGroup>` and `<Card>` for navigation elements
18+
- Code blocks should specify language when applicable
19+
- Images should be placed in `/images/` organized by feature area
20+
21+
## Documentation Commands
22+
- Preview: npx mintlify dev
23+
- Build: npx mintlify build
24+
- Deploy: npx mintlify deploy
25+
26+
## Content Best Practices
27+
- Keep descriptions concise and action-oriented
28+
- Use consistent terminology throughout documentation
29+
- Link related concepts for better navigation
30+
- Example code should be complete and tested
31+
- Maintain OpenAPI reference in sync with API implementation

‎api-reference/introduction.mdx

+20-18
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,30 @@
11
---
2-
title: "Introduction"
2+
title: "API Introduction"
33
description: |
4-
Ctrlplane API reference
4+
Complete reference for the Ctrlplane REST API
55
---
66

7-
OpenAPI (formerly known as Swagger) is a standardized specification for
8-
describing REST APIs. It provides a way to document API's endpoints,
9-
request/response formats, authentication methods, and other details in a
10-
machine-readable format.
7+
## API Overview
118

12-
The OpenAPI specification makes it easier to:
9+
The Ctrlplane API enables programmatic access to all platform functionality, allowing you to automate deployments, manage resources, and integrate with your existing tools.
1310

14-
- Auto-generate API client libraries
15-
- Enable API discovery and exploration
11+
## API Structure
1612

17-
Our OpenAPI specification contains detailed information about all available
18-
Ctrlplane API endpoints, including:
13+
Our API follows OpenAPI standards (formerly Swagger) with these key features:
1914

20-
- Available HTTP methods (GET, POST, PUT, DELETE etc.)
21-
- Request parameters and body schemas
22-
- Response formats and status codes
15+
- **RESTful Design**: Resource-based endpoints with standard HTTP methods
16+
- **JSON Payloads**: Consistent request/response format
17+
- **Key Authentication**: Simple API key authentication
18+
- **Comprehensive Endpoints**: Complete coverage of platform functionality
19+
20+
## Documentation Structure
21+
22+
The API documentation includes:
23+
24+
- HTTP methods (GET, POST, PUT, DELETE)
25+
- Required and optional parameters
26+
- Request/response schemas with examples
2327
- Authentication requirements
24-
- Examples and descriptions
28+
- Status codes and error handling
2529

26-
View the
27-
[OpenAPI](https://github.com/ctrlplanedev/ctrlplane/blob/main/openapi.v1.json)
28-
spec.
30+
View the complete [OpenAPI specification](https://github.com/ctrlplanedev/ctrlplane/blob/main/openapi.v1.json) on GitHub.

‎concepts/environments.mdx

+1-4
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,7 @@
11
---
22
title: Environments
33
description: |
4-
Environments in Ctrlplane are logical groupings of resources that represent
5-
distinct stages in your software deployment pipeline. They are defined at the
6-
system level and play a crucial role in organizing and managing the deployment
7-
process across various infrastructure components.
4+
Environments are system-level resource groupings that represent distinct deployment stages (like dev, staging, production) and control how software progresses through your infrastructure.
85
---
96

107
<iframe

‎concepts/systems.mdx

+1-4
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,7 @@
11
---
22
title: Systems
33
description: |
4-
Systems in Ctrlplane are the highest level of organizational units, designed to
5-
group related deployments and environments together. They provide a structured
6-
approach to managing complex deployment pipelines and enforcing consistency
7-
across your infrastructure.
4+
Systems are the highest level organizational units in Ctrlplane that group related deployments and environments together for consistent management.
85
---
96

107
<iframe

‎examples/advanced/ephemeral-environments.mdx

+26-35
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,35 @@
11
---
22
title: Ephemeral Environments
3-
description: Ephemeral Environments are a way to create and destroy environments on demand.
3+
description: Create and destroy isolated testing environments automatically based on pull requests or other triggers to optimize your development workflow.
44
---
55

6-
## Determining if you need an ephemeral environment
6+
## Is Ephemeral Environments Right for Your Team?
77

8-
Here are some key questions to help determine if ephemeral environments would benefit your workflow:
8+
Consider these key questions to determine if ephemeral environments would benefit your workflow:
99

1010
<AccordionGroup>
1111
<Accordion title="Do you need isolated testing environments?">
12-
If your team needs to test features in isolation without impacting other developers or staging environments, ephemeral environments allow you to spin up dedicated environments on-demand.
12+
Ephemeral environments provide isolated testing spaces for each feature or branch, preventing conflicts between developers and ensuring clean test conditions for every change.
1313
</Accordion>
1414

15-
<Accordion title="Are your environments complex to set up?">
16-
When environments require multiple services, databases, and configurations to
17-
be set up, ephemeral environments can automate this process and ensure
18-
consistency.
19-
</Accordion>
20-
21-
<Accordion title="Do you have high infrastructure costs?">
22-
If maintaining multiple long-running environments is costly, ephemeral
23-
environments can help reduce costs by only running when needed and
24-
automatically cleaning up unused resources.
25-
</Accordion>
26-
27-
<Accordion title="Do you need to test branch-specific changes?">
28-
Ephemeral environments make it easy to test changes from specific branches by
29-
creating isolated environments that match your branch configuration.
30-
</Accordion>
31-
32-
<Accordion title="Is your team growing?"> As teams scale, coordinating
33-
environment usage becomes more challenging. Ephemeral environments give each
34-
developer or team their own space to work without interference. </Accordion>
15+
<Accordion title="Are your environments complex to set up?">
16+
When environments require multiple services, databases, and configurations, ephemeral environments automate this complex process, ensuring consistent setups every time and saving hours of manual configuration.
17+
</Accordion>
18+
19+
<Accordion title="Do you have high infrastructure costs?">
20+
By automatically creating environments when needed and destroying them when work is complete, ephemeral environments can significantly reduce cloud infrastructure costs compared to maintaining multiple permanent environments.
21+
</Accordion>
22+
23+
<Accordion title="Do you need to test branch-specific changes?">
24+
Ephemeral environments create isolated testing spaces that exactly match your branch configuration, making it easy to validate changes in context before merging to the main codebase.
25+
</Accordion>
26+
27+
<Accordion title="Is your team growing?">
28+
As teams scale, coordinating environment usage becomes increasingly challenging. Ephemeral environments eliminate contention by giving each developer or team their own dedicated space to work without interference.
29+
</Accordion>
3530
</AccordionGroup>
3631

37-
If you answered yes to any of these questions, implementing ephemeral
38-
environments could significantly improve your development workflow.
32+
If you answered yes to any of these questions, implementing ephemeral environments with Ctrlplane could significantly improve your development workflow and reduce operational overhead.
3933

4034
## Scenario
4135

@@ -70,18 +64,15 @@ graph TD
7064

7165
## 1. Pull Request Resource Creation
7266

73-
When using Ctrlplane for any system, you must first determine what resources
74-
represent the the existance of your deployment.
67+
When using Ctrlplane for any system, you must first determine what resources represent the existence of your deployment.
7568

76-
In this case, we will use the GitHub pull request to determine if the ephemeral
77-
environment should be created and when it should be destroyed.
69+
In this case, we'll use GitHub pull requests to determine when ephemeral environments should be created and destroyed.
7870

79-
This means Ctrlplane will follow the lifecycle of the pull request - creating
80-
the environment when the PR is opened and destroying it when the PR is merged or
81-
closed.
71+
This approach means Ctrlplane will follow the PR lifecycle:
72+
- Creating the environment when a PR is opened
73+
- Destroying it when the PR is merged or closed
8274

83-
todo this we will need to create a Github that tracks and updates resources in
84-
ctrlplane as pull requests state changes.
75+
To implement this workflow, we'll create a GitHub workflow that tracks PR state changes and updates resources in Ctrlplane accordingly.
8576

8677
Here is what it does:
8778

‎getting-started/define-and-use-variables.mdx

+52-11
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,63 @@
11
---
22
title: Define and Use Variables
33
description: |
4-
Learn how to define and use variables in Ctrlplane to create flexible and
5-
reusable deployment configurations across environments.
4+
Learn how to create flexible, reusable deployment configurations with Ctrlplane variables
65
---
76

87
## Overview
98

10-
Variables in Ctrlplane allow you to create dynamic and reusable deployment
11-
configurations. By using variables, you can maintain consistent deployment
12-
processes while accommodating differences across environments, resources, and
13-
release channels.
9+
Variables in Ctrlplane make your deployments dynamic and adaptable. They let you maintain consistent processes while accommodating differences across environments, resources, and releases.
1410

1511
## Variable Types
1612

17-
Ctrlplane supports several types of variables:
13+
Ctrlplane supports four primary variable types:
1814

19-
- **Environment Variables**: Specific to deployment environments
20-
- **System Variables**: Available across an entire system
21-
- **Resource Variables**: Tied to specific resources
22-
- **Release Variables**: Associated with specific releases
15+
- **Environment Variables**: Values specific to each environment (dev, staging, production)
16+
- Example: `database_url`, `log_level`, `api_endpoint`
17+
18+
- **System Variables**: Values shared across your entire system
19+
- Example: `company_name`, `team_id`, `global_timeout`
20+
21+
- **Resource Variables**: Values specific to individual resources
22+
- Example: `server_ip`, `instance_size`, `memory_allocation`
23+
24+
- **Release Variables**: Values tied to specific software releases
25+
- Example: `version`, `release_notes`, `build_commit`
26+
27+
## Defining Variables
28+
29+
Variables can be defined in the Ctrlplane UI or API:
30+
31+
1. Navigate to the appropriate section (Environment, System, Resource, or Release)
32+
2. Select "Variables" or "Configuration"
33+
3. Add variable key-value pairs
34+
4. Save your changes
35+
36+
## Using Variables in Deployments
37+
38+
Reference variables in your deployment scripts using double curly braces:
39+
40+
```bash
41+
# Environment variable
42+
echo "Connecting to database at {{.environment.database_url}}"
43+
44+
# System variable
45+
echo "Deploying for {{.system.company_name}}"
46+
47+
# Resource variable
48+
echo "Server IP address: {{.resource.server_ip}}"
49+
50+
# Release variable
51+
echo "Deploying version {{.release.version}}"
52+
```
53+
54+
## Variable Inheritance and Precedence
55+
56+
When variables with the same name exist at different levels:
57+
58+
1. Resource variables take highest precedence
59+
2. Release variables are next
60+
3. Environment variables follow
61+
4. System variables have lowest precedence
62+
63+
This hierarchy lets you define defaults at the system level while overriding them for specific environments, releases, or resources.

‎getting-started/first-deployment.mdx

+21-22
Original file line numberDiff line numberDiff line change
@@ -1,42 +1,41 @@
11
---
2-
title: First Deployment
2+
title: Your First Deployment
33
description: |
4-
Learn how to make your first deployment with Ctrlplane by following this tutorial.
5-
We'll create a simple hello world deployment that can run across multiple servers.
4+
Follow this step-by-step guide to create your first Ctrlplane deployment - a simple "hello world" example that demonstrates the core workflow.
65
---
76

8-
Before starting, ensure you have:
7+
## Prerequisites
98

10-
- Access to a Ctrlplane Workspace (cloud-hosted or self-hosted)
11-
- The Ctrlplane CLI installed
9+
Before starting, you'll need:
1210

13-
## Create a new System
11+
- A Ctrlplane Workspace (cloud-hosted or self-hosted)
12+
- The Ctrlplane CLI installed on your local machine
1413

15-
Systems organize related deployments and environments into logical groups,
16-
making it easier to manage deployment pipelines and maintain consistency across
17-
your infrastructure.
14+
## Step 1: Create a System
1815

19-
To create a new system:
16+
A System in Ctrlplane organizes related deployments and environments into logical groups. This structure helps maintain consistency and simplifies management.
2017

21-
1. Click the `+` button in the top left corner to open the menu
22-
2. Select `New System` from the dropdown
23-
3. Give your system a descriptive name, for example, `Hello world`.
18+
To create your first system:
19+
20+
1. In the Ctrlplane UI, click the `+` button in the top left corner
21+
2. Select `New System` from the dropdown menu
22+
3. Enter a descriptive name (e.g., `Hello World Demo`)
2423

2524
<Frame>
2625
<img src="/images/first-deployment/new-system-dialog.png" />
2726
</Frame>
2827

29-
## Create a new Deployment
28+
## Step 2: Create a Deployment
3029

31-
A deployment represents a complete, end-to-end process for delivering changes to
32-
your system, organizing principle for managing and orchestrating the release of
33-
your software or infrastructure across various environments within a system.
30+
A Deployment in Ctrlplane represents a complete delivery process for your software or infrastructure. It orchestrates how changes move through your environments.
3431

35-
1. Click the `+` button in the top left corner to open the menu
32+
To create a deployment:
33+
34+
1. Click the `+` button in the top left corner
3635
2. Select `New Deployment` from the dropdown
37-
3. For this example, keep the default option selected.
38-
4. Give your deployment a descriptive name, for example, `My First Deployment`.
39-
5. Click `Create`.
36+
3. Keep the default option selected for this example
37+
4. Enter a name for your deployment (e.g., `Hello World Deployment`)
38+
5. Click `Create`
4039

4140
<Frame>
4241
<img src="/images/first-deployment/new-deployment-dialog.png" />

‎introduction.mdx

+4-7
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,14 @@
11
---
2-
title: "Intro to Ctrlplane"
2+
title: "Introduction to Ctrlplane"
33
description: |
4-
Ctrlplane is an open-source deployment orchestration tool that helps you scale
5-
your infrastructure.
4+
Ctrlplane is an open-source deployment orchestration tool that simplifies complex infrastructure management and scaling.
65
---
76

87
## What you can do with Ctrlplane
98

10-
Ctrlplane is designed to streamline and automate complex deployment processes
11-
across diverse infrastructures, helping teams scale their operations efficiently
12-
and securely.
9+
Ctrlplane streamlines and automates complex deployment processes across diverse infrastructures, helping teams scale operations efficiently and securely.
1310

14-
Here's an overview of Ctrlplane's key capabilities and common use cases.
11+
Here's what Ctrlplane offers:
1512

1613
| Capability | Enables you to... |
1714
| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ |

‎overview.mdx

+10-12
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,19 @@
11
---
22
title: Overview
33
description: |
4-
Ctrlplane is an open-source deployment orchestration tool that
5-
helps you scale your infrastructure.
4+
Ctrlplane simplifies infrastructure scaling through powerful deployment orchestration.
65
---
76

8-
Ctrlplane is an open-source deployment orchestration tool designed to streamline
9-
and manage complex deployment processes across diverse infrastructures. It
10-
provides a centralized platform for coordinating deployments, ensuring
11-
consistency, and enhancing scalability.
7+
Ctrlplane provides a centralized platform for coordinating deployments, ensuring consistency, and enhancing scalability across diverse infrastructures.
128

13-
- Integration with existing CI/CD tools
14-
- Advanced orchestration policies
15-
- Automation and synchronization of deployment activities
16-
- Version management
17-
- Environment standardization
18-
- Resource/CI analysis
9+
## Key Features
10+
11+
- **CI/CD Integration**: Seamlessly works with your existing CI/CD pipeline
12+
- **Policy-Based Orchestration**: Define and enforce deployment rules
13+
- **Automated Workflows**: Synchronize complex deployment activities
14+
- **Version Control**: Track and manage software releases
15+
- **Environment Management**: Standardize deployment environments
16+
- **Resource Analysis**: Gain insights into your infrastructure
1917

2018
---
2119

0 commit comments

Comments
 (0)