From a3295c561ac72e11055fd6107d4d01d3a4362432 Mon Sep 17 00:00:00 2001 From: Johnny Huynh <27847622+johnnyhuy@users.noreply.github.com> Date: Sat, 14 Nov 2026 03:10:13 +0700 Subject: [PATCH] docs: refresh local demo and analytics setup guides Replace removed make targets with the existing mise workflow and explain guest access, configuration, and the optional analytics stack. Co-authored-by: OpenAI Codex --- docs/index.md | 82 +++++++++++++++++++++++++++--------------------- docs/tracking.md | 61 ++++++++++++++++++++++++++++------- 2 files changed, 97 insertions(+), 46 deletions(-) diff --git a/docs/index.md b/docs/index.md index 0846ced..6c4a934 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,56 +1,68 @@ # Backstage -## 🚀 Getting Started +## Run the demo locally -To run the Backstage Showcase locally: +Install [mise](https://mise.jdx.dev/), trust the repository configuration after +reviewing `mise.toml`, and use the tool versions declared there. Run the tasks +from the repository root. -1. Clone the repository - ``` +1. Clone the repository and enter it. + + ```bash git clone https://github.com/echohello-dev/backstage.git + cd backstage ``` -2. Install dependencies - ``` - make install - ``` -3. Start the app - ``` - make dev + +2. Install dependencies and prepare the local configuration. + + ```bash + mise run install ``` -4. Open [`localhost:3000`](http://localhost:3000) in your browser -## 🧑‍💻 Development + This copies `.env.example` to `.env` and `app-config.example.yaml` to + `app-config.local.yaml` when those files are missing. Existing local files + are preserved. Keep local credentials in these gitignored files. -Common development tasks can be executed using `make` commands: +3. Start the frontend and backend. - -Command | Description --|- -`make login` | Authenticate with Kubernetes and GitHub -`make dev` | Start a local development server -`make test` | Run tests -`make build` | Build a Docker image -`make deploy` | Deploy to Kubernetes -`make encrypt` | Encrypt sensitive files -`make decrypt` | Decrypt sensitive files + ```bash + mise run dev + ``` -## Upgrading Backstage +4. Open [localhost:3000](http://localhost:3000), choose Guest, then Enter. + The backend runs on [localhost:7007](http://localhost:7007). Stop the + development stack with Ctrl+C in its terminal. -```bash -yarn backstage-cli versions:bump -``` +Guest access is read-only. You can browse the showcase, catalog, TechDocs and +software templates, but running a template requires developer permissions. +See the [demo baseline](demo-baseline.md) for the access rules and known limits. +The local catalog uses an in-memory database that resets when the backend restarts. +The default development stack does not require Docker; the optional Compose +stack below does. -[Reference](https://backstage.io/docs/getting-started/keeping-backstage-updated/) +## Development tasks -## Configuration API Reference +All tasks run through mise. See the [development guide](development.md) for +verification details and TechDocs troubleshooting. -Use the following command to get the configuration API reference. +| Command | Description | +| ------------------ | -------------------------------------------------------- | +| `mise run install` | Install dependencies and prepare local configuration | +| `mise run dev` | Start the frontend on port 3000 and backend on port 7007 | +| `mise run lint` | Run TypeScript checks and ESLint across the workspaces | +| `mise run test` | Run the test suite without watch mode | +| `mise run build` | Build the Docker image locally, without publishing it | +| `mise run up` | Start Backstage with Traefik using Docker Compose | +| `mise run down` | Stop the Backstage and Traefik Compose stack | -```bash -yarn backstage-cli config:docs -``` +The Compose stack serves Backstage at [backstage.localhost](http://backstage.localhost) +and uses the production configuration and `.env` values. Review those values before +starting it. See the [tracking guide](tracking.md) for the optional Plausible stack. -## Development +## Backstage references +- [Keeping Backstage Updated](https://backstage.io/docs/getting-started/keeping-backstage-updated/) +- [Configuration](https://backstage.io/docs/conf/) - [Loading Configuration](https://backstage.io/docs/conf/reading) - [New Backend System](https://backstage.io/docs/backend-system/) - [Migrating to New Auth Services](https://backstage.io/docs/tutorials/auth-service-migration/) diff --git a/docs/tracking.md b/docs/tracking.md index 69f7104..faca128 100644 --- a/docs/tracking.md +++ b/docs/tracking.md @@ -1,25 +1,64 @@ # Tracking -We use Plausible Analytics to track visits to our website. Plausible is a privacy-friendly alternative to Google Analytics. It does not use cookies and does not collect any personal data. You can read more about Plausible's data policy [here](https://plausible.io/data-policy). +The portal includes a Plausible Analytics integration. Analytics is disabled in +`app-config.yaml` for local development and enabled in the production config. +The frontend adds the tracking script only when `plausible.enabled` is true and +both `plausible.dataDomain` and `plausible.sourceUrl` are set. -## Local Development +## Optional local analytics stack -To run the Plausible Analytics server locally, you can use the following command: +Start with the [local demo setup](index.md#run-the-demo-locally). The analytics +stack additionally requires a running Docker daemon and Docker Compose, with +ports 80, 8080, 7007 and 8000 available. It starts Backstage and Traefik as well +as Plausible, PostgreSQL and ClickHouse. Stop `mise run dev` before starting +this stack to free the backend port. -```bash -make plausible-up +In the gitignored `.env`, set `SECRET_KEY_BASE` and `TOTP_VAULT_KEY` for Plausible. +The starter file leaves them commented out. Use the secret-generation guidance +for the pinned Plausible Community Edition version in `compose.plausible.yaml`. +The starter Backstage analytics settings are already present in `.env`. + +```dotenv +APP_BASE_URL=http://backstage.localhost +PLAUSIBLE_DATA_DOMAIN=backstage.localhost +PLAUSIBLE_SOURCE_URL=http://plausible.localhost/js/script.js +BASE_URL=http://plausible.localhost ``` -Build the app and start the server: +Build the local Backstage image, then start the combined Compose stack from the +repository root. ```bash -make build -make up +mise run build +mise run plausible-up +``` + +Open [plausible.localhost](http://plausible.localhost) to finish Plausible setup +and add a site matching `PLAUSIBLE_DATA_DOMAIN`. Backstage runs at +[backstage.localhost](http://backstage.localhost). The production configuration +reads `PLAUSIBLE_DATA_DOMAIN` and `PLAUSIBLE_SOURCE_URL` from `.env`; the local +development configuration does not read those variables for analytics. + +To connect `mise run dev` to a separately running Plausible instance, merge the +following top-level settings into `app-config.local.yaml`, replacing the script +URL with that instance's address. Restart the development stack after editing +the config. Use a site domain matching the address you browse. + +```yaml +plausible: + enabled: true + dataDomain: localhost + sourceUrl: https://plausible.example.com/js/script.js ``` -To tear down the server: +The script tag confirms that the plugin is configured. It does not prove that +Plausible accepted an event; check browser network requests and the Plausible +dashboard when verifying collection. + +Stop the combined analytics stack with the matching task. ```bash -make plausible-down -make down +mise run plausible-down ``` + +This stops the services without deleting their named database volumes.