Skip to content

docs: refresh local demo and analytics setup guides #136

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
johnnyhuy wants to merge 1 commit into
base: main
Choose a base branch
from
+97 −46
Open

docs: refresh local demo and analytics setup guides #136

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 47 additions & 35 deletions docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.

<!-- prettier-ignore -->
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/)
Expand Down
61 changes: 50 additions & 11 deletions docs/tracking.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Loading