backstage / backstage/backstage

🚀 Feature: Write start and stop instructions for production Backstage server

Open
#21,916 3 comments 0 reactions 0 assignees View on GitHub
area:documentation area:microsite no stale type:suggestion
Dominant language
TypeScript
Stars
34.4k
Forks
7.6k
Avg merge
8h 57m
Merged PRs (30d)
50

Description

### 🔖 Feature description

### Write start, stop, and other instructions for production Backstage server

Write step-by-step instructions to start, restart, check status, and stop a production Backstage server. Include a procedure for every install configuration (Kubernetes, standalone, etc.). Add procedures for any other server-related actions needed by the admin. Can also include sections on tuning server performance in each case. Organize under *Admin Guide* in the doc TOC.

Audience: Admin

Type: Task

The existing documentation might contain helpful source material that you can pull into this doc change. See this catalog of the existing (at the time of the CNCF tech doc analysis) Backstage technical documentation pages:
https://github.com/cncf/techdocs/blob/main/assessments/0008-backstage/backstage-doc-survey.csv

### 🎤 Context

This issue is a recommended change resulting from an analysis of the Backstage documentation commissioned by CNCF. The analysis and supporting documents are here:
https://github.com/cncf/techdocs/tree/main/assessments/0008-backstage

### ✌️ Possible Implementation

The goal here is to create a run book that an Admin can refer to quickly as part of an Admin guide that also includes troubleshooting, performance, upgrading, and so on.

Suggested changes:
- Include in each procedure, if applicable, "Prerequisites" and "What's next" sections.
- Write as step-by-step instructions. In some cases these might be very short; that's OK.
- A procedure might be fairly elaborate in some cases; for example, on a Kubernetes-based app. That's OK too.
- Add procedures for any other server actions an Admin might need in administering the Backstage app.
- Include links to the Admin troubleshooting section.
- Add procedures to the table of contents in the (new) Admin Guide section.

### 👀 Have you spent some time to check if this feature request has been raised before?

- [X] I checked and didn't find similar issue

### 🏢 Have you read the Code of Conduct?

- [X] I have read the [Code of Conduct](https://github.com/backstage/backstage/blob/master/CODE_OF_CONDUCT.md)

### Are you willing to submit PR?

None

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the existing Backstage documentation catalog and the CNCF assessment linked in the issue to identify reusable source material. Inventory the production procedures needed for Kubernetes and standalone installations, then organize step-by-step start, restart, status, stop, and related admin actions under the Admin Guide in the documentation table of contents. Done means the runbook includes applicable prerequisites, next steps, performance guidance, and troubleshooting links.

Written by the indexing model from the issue text.

Assessment

Tech stack
kubernetes
Domain
devops, documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
28/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.