Skip to content

Commit 82a81d9

Browse files
kurtakingkurtaking
authored
announcements: improve seed data and local dev docs (#6501)
* rehaul of local dev seed data and docs Signed-off-by: Kurt King <[email protected]> * Add changesets Signed-off-by: Kurt King <[email protected]> --------- Signed-off-by: Kurt King <[email protected]>
1 parent 1de1a07 commit 82a81d9

File tree

11 files changed

+1453
-658
lines changed

11 files changed

+1453
-658
lines changed

‎workspaces/announcements/.changeset/clean-pillows-do.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
'@backstage-community/plugin-announcements-backend': patch
3+
---
4+
5+
A few README file updates
6+
7+
- added integrations section with links to supported integrations (search, permission, events, signals, notifications)
8+
- improved local development instructions on postgres with added isntructions on seeding the database

‎workspaces/announcements/.changeset/perfect-news-pretend.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'@backstage-community/plugin-search-backend-module-announcements': patch
3+
---
4+
5+
Added installation instructions to the README.

‎workspaces/announcements/app-config.local.yaml.sample‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
backend:
2+
database:
3+
client: pg
4+
connection:
5+
host: ${POSTGRES_HOST}
6+
port: ${POSTGRES_PORT}
7+
user: ${POSTGRES_USER}
8+
password: ${POSTGRES_PASSWORD}
9+
10+
auth:
11+
providers:
12+
# allows you to select a user and group to be the owner of the announcement
13+
# when creating announcements locally
14+
guest:
15+
userEntityRef: user:default/user-1
16+
ownershipEntityRefs: [group:default/team-a]
17+
dangerouslyAllowOutsideDevelopment: false

‎workspaces/announcements/env.sample‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
# defaults to better-sqlite
2+
PLUGIN_ANNOUNCEMENTS_KNEX_CLIENT=pg
3+
14
POSTGRES_HOST=localhost
25
POSTGRES_PORT=5432
36
POSTGRES_USER=postgres

‎workspaces/announcements/plugins/announcements-backend/README.md‎

Lines changed: 82 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,25 @@
33
The backend for the Announcements plugin. This plugin provides:
44

55
- REST APIs for managing announcements, categories, and tags
6+
- Database model for storing announcements, categories, and tags
67
- Integration with the [`@backstage/plugin-search`](https://github.com/backstage/backstage/tree/master/plugins/search) plugin
78
- Integration with the [`@backstage/plugin-permission-backend`](https://github.com/backstage/backstage/tree/master/plugins/permission-backend) plugin
89
- Integration with the [`@backstage/plugin-events-backend`](https://github.com/backstage/backstage/tree/master/plugins/events-backend) plugin
910
- Integration with the [`@backstage/plugin-signals-backend`](https://github.com/backstage/backstage/tree/master/plugins/signals-backend) plugin
1011
- Integration with the [`@backstage/notifications-backend`](https://github.com/backstage/backstage/tree/master/plugins/notifications-backend) plugin
1112
- Integration with the [Auditor Service](https://backstage.io/docs/backend-system/core-services/auditor). Audit logging helps to track announcements creation, updates, and deletion.
1213

14+
## Table of contents
15+
16+
- [Installation](#installation)
17+
- [API Examples](#api-examples)
18+
- [Integrations](#integrations)
19+
- [Local development](#local-development)
20+
- [Setup](#setup)
21+
- [Database](#database)
22+
- [Postgres](#postgres)
23+
- [Seeding the database](#seeding-the-database)
24+
1325
## Installation
1426

1527
To install it to your backend package, run the following command:
@@ -27,7 +39,55 @@ const backend = createBackend();
2739
backend.add(import('@backstage-community/plugin-announcements-backend'));
2840
```
2941

30-
## Development
42+
## API examples
43+
44+
```sh
45+
# get all announcements
46+
curl http://localhost:7007/api/announcements/announcements
47+
48+
# get all categories
49+
curl http://localhost:7007/api/categories
50+
51+
# get all tags
52+
curl http://localhost:7007/api/tags
53+
```
54+
55+
```ts
56+
// get all announcements
57+
const response = await fetch(
58+
'http://localhost:7007/api/announcements/announcements',
59+
);
60+
const data = await response.json();
61+
return data;
62+
```
63+
64+
## Integrations
65+
66+
The announcements plugin integrates with the following Backstage plugins.
67+
68+
### Permission
69+
70+
View the [permission](../announcements-common/README.md#resources) documentation.
71+
72+
### Events
73+
74+
View the [events](../announcements-node/docs/events.md) documentation.
75+
76+
### Signals
77+
78+
View the [signals](../announcements-node/docs/signals.md) documentation.
79+
80+
### Notifications
81+
82+
Backstage's Notification System enables plugins and services to deliver real-time alerts to users, visible in the UI or via external channels. The announcements plugin can send a notification through the Notifications backend whenever an announcement is created. Announcement notifications are disabled by default and can be enabled via the `sendNotification` option when creating an announcement in the UI.
83+
84+
See the notifications [docs](https://backstage.io/docs/notifications/).
85+
86+
### Search
87+
88+
View the search module's [README](../search-backend-module-announcements/README.md).
89+
90+
## Local development
3191

3292
This plugin backend can be started in a standalone mode from directly in this
3393
package with `yarn start`. It is a limited setup that is most convenient when
@@ -41,76 +101,50 @@ If you want to run the entire project, including the frontend, run `yarn start`
41101
# install dependencies
42102
yarn install
43103

44-
# set .env
45-
cp env.sample .env
46-
source .env
47-
48-
# start the backend
104+
# start the backend with in-memory database
49105
yarn start
50106
```
51107

52108
### Database
53109

54-
The plugin includes support for postgres and better-sqlite3 databases. By default, the plugin uses a postgres database via docker-compose. Update the `app-config.yaml` to use the `better-sqlite3` database.
110+
The plugin defaults to better-sqlite3 in the main `app-config.yaml`. If you want to use postgres, you can via docker-compose. We recommend you copy the `app-config.local.yaml.sample` to `app-config.local.yaml` and update the database configuration.
111+
112+
The postgres database can be seeded with categories, tags, and announcements.
55113

56114
#### Postgres
57115

58-
The postgres database can be started with docker-compose. Don't forget to copy the `env.sample`.
116+
The postgres database can be started with docker-compose. You will need to copy the `env.sample` to `.env`, the `app-config.local.yaml.sample` to `app-config.local.yaml`.
59117

60118
```sh
119+
# copy the env.sample to .env
120+
cp env.sample .env
121+
122+
# copy the app-config.local.yaml.sample to app-config.local.yaml
123+
cp app-config.local.yaml.sample app-config.local.yaml
124+
61125
# start the postgres database
62126
docker-compose up -d
63127

64128
# stop the postgres database
65129
docker-compose down -v
66-
```
67130

68-
#### better-sqlite3
131+
# start the backend with postgres database
132+
yarn start
133+
```
69134

70-
The better-sqlite3 database can be seeded with categories, tags, and announcements.
135+
#### Seeding the database
71136

72-
With the backend running,
137+
The postgres database can be seeded with categories, tags, and announcements.
73138

74139
```sh
75-
# runs migrations and seeds the database
140+
# initial or reset the database
76141
yarn db:setup
77-
78-
# or run them separately
79-
yarn db:migrations
80-
yarn db:seed
81142
```
82143

83-
This will create a `local.sqlite` file under the `db/` directory.
84-
85-
Visit [knexjs](https://knexjs.org/guide/migrations.html) to learn more about the database migrations and seeding.
86-
87-
### API Examples
88-
89144
```sh
90-
# get all announcements
91-
curl http://localhost:7007/api/announcements/announcements
92-
93-
# get all categories
94-
curl http://localhost:7007/api/categories
95-
96-
# get all tags
97-
curl http://localhost:7007/api/tags
98-
```
145+
# running migrations
146+
yarn db:migrations
99147

100-
```ts
101-
// get all announcements
102-
const response = await fetch(
103-
'http://localhost:7007/api/announcements/announcements',
104-
);
105-
const data = await response.json();
106-
return data;
148+
# seeding the database
149+
yarn db:seed
107150
```
108-
109-
### Notifications for Announcements
110-
111-
Backstage’s Notification System empowers plugins and services to deliver alerts to users and is directly visible in the UI or via external channels. Visit the [docs](https://backstage.io/docs/notifications/) on notifications for more information.
112-
113-
The Notification plugin delivers real-time alerting, with backend/frontend components to send and display notifications - including push signals.
114-
To trigger alerts when a new announcement appears, you can combine these systems: send a notification via the Notifications backend whenever an announcement is created.
115-
116-
Announcement notifications are disabled by-default. Notifications can be sent if "sendNotification" option in the UI is enabled.

‎workspaces/announcements/plugins/announcements-backend/db/seeds/01_categories.js‎

Lines changed: 8 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -22,17 +22,15 @@ exports.seed = async function seed(knex) {
2222
// Deletes ALL existing entries
2323
await knex('categories').del();
2424
await knex('categories').insert([
25-
{ slug: 'infrastructure', title: 'Infrastructure' },
26-
{ slug: 'internal-developer-portal', title: 'IDP' },
27-
{ slug: 'cost-savings', title: 'Cost Savings' },
28-
{ slug: 'javascript', title: 'Javascript' },
29-
{ slug: 'ruby-on-rails', title: 'Ruby on Rails' },
30-
{ slug: 'monolith', title: 'Monolith' },
31-
{ slug: 'micro-service', title: 'Micro Service' },
32-
{ slug: 'engineering-community', title: 'Engineering Community' },
33-
{ slug: 'product-updates', title: 'Product Updates' },
25+
{ slug: 'platform-updates', title: 'Platform Updates' },
3426
{ slug: 'security', title: 'Security' },
35-
{ slug: 'documentation', title: 'Documenation' },
27+
{ slug: 'maintenance', title: 'Maintenance' },
28+
{ slug: 'new-features', title: 'New Features' },
29+
{ slug: 'deprecations', title: 'Deprecations' },
30+
{ slug: 'best-practices', title: 'Best Practices' },
31+
{ slug: 'incidents', title: 'Incidents' },
3632
{ slug: 'events', title: 'Events' },
33+
{ slug: 'documentation', title: 'Documentation' },
34+
{ slug: 'community', title: 'Community' },
3735
]);
3836
};

0 commit comments

Comments
 (0)