Skip to content

Improve setup documentation, sample artifacts, and Redis/TLS configuration #596

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

Draft
Shamly-Shanawaz wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

Improve setup documentation, sample artifacts, and Redis/TLS configuration #596

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9db6ec1
Improve setup docs and scripts, sample data, and Redis/TLS config
Shamly-Shanawaz Dec 16, 2025
44e1159
Merge remote-tracking branch 'upstream/main'
Shamly-Shanawaz Dec 16, 2025
f95f11b
Update README to clarify certificate/key file placement for Dev confi…
Shamly-Shanawaz Dec 16, 2025
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
375 changes: 244 additions & 131 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,155 +1,268 @@
**Pre-requisites**
Install Node.js v22.0.0
Install POSTGRESQL and create a database named 'devportal'.
For more information, refer to docs/InstallationGuide.md.
## Prerequisites

**Changing the database to PostgreSQL**
- **Node.js**: v22.0.0
- **PostgreSQL**

## Required files

The app expects a `config.json` and `secret.json` in the repo root.

Create them from the samples:

1. Navigate to the config.json file in the <DEVPORTAL_HOME> directory.

2. Edit the db properties to connect to the created db.

```bash
db = {
cp sample_config.json config.json
cp sample_secret.json secret.json
```

## Connect to the Dev environment

If you want to connect to the **Dev environment**, you need to replace your local `config.json` and `secret.json` with the **Dev Devportal** versions.

    username: 'postgres',
- Request the **Dev** `config.json` and `secret.json` from the team.
- Request the required **certificate(s) / key file(s)** from the team as well (if the Dev setup uses TLS/SSL).
- Replace the files in the repo root:
- `./config.json`
- `./secret.json`

    password: 'postgres',
If the Dev configuration uses certificates/keys, place the provided files at the paths referenced in your `config.json` (e.g., `pathToDBCert`, `serverCerts.*`). The Dev config typically points under `./resources/security/`, so if you keep those values, create the folder:

    database: 'devportal',
```bash
mkdir -p resources/security
```

Then copy the provided cert/key files into that folder.

    host: 'localhost',
### Install and run

```bash
npm install
npm start
```

    dialect: 'postgres'
### TLS / self-signed certificate errors (PostgreSQL)

If you see an error like `self-signed certificate in certificate chain` coming from Sequelize when connecting to Postgres, you can **temporarily** test the connection by relaxing TLS validation for the DB connection:

- Open `src/db/sequelize.js`
- In the `ssl` options passed to Sequelize, change:
- from: `rejectUnauthorized: true,`
- to: `rejectUnauthorized: false,`

**Important:** this is only for local troubleshooting. **Do not commit** `rejectUnauthorized: false` to the repo; revert it back to `true` (or reset the file) once you’ve validated your setup.


If you are connecting to the **Dev environment**, you can skip everything below in this README.

## Local Setup

### Configure `config.json`

For local development, it’s easiest to run over **HTTP** (no cert files needed). Update these keys in the config.json:

```json
{
"advanced": {
"http": true
},
"baseUrl": "http://localhost:3000",
"defaultPort": 3000
}
```

**Try Out Devportal**
### Configure Identity Provider (login)

The login flows depend on the Identity Provider settings in `config.json` under `identityProvider`. If these values are incorrect (or left as empty strings), the login flow will fail.

In the sample configs, the IdP endpoints often point to `https://localhost:9443/...` (a local Identity Server). If you don’t have an IdP running there, update the following keys to match your actual IdP:

- `identityProvider.issuer`
- `identityProvider.authorizationURL`
- `identityProvider.tokenURL`
- `identityProvider.userInfoURL`
- `identityProvider.jwksURL`
- `identityProvider.clientId`
- `identityProvider.callbackURL` (should match your app URL)

### Database setup

#### 0) Create database

Create a database named `devportal`:

```bash
createdb -h <HOST> -U <USER> devportal
```

Or, run PostgreSQL using Docker and create the database:

1. Run the following command to create a default organization and populate the developer portal landing page content.
```bash
./artifacts/org_data.sh
```
```bash
docker run --name devportal-postgres \
-e POSTGRES_USER=postgres \
-e POSTGRES_PASSWORD=postgres \
-e POSTGRES_DB=devportal \
-p 5432:5432 \
-d postgres:16
```

2. Run the following command to create mock APIs and populate api landing page content.
For the DB user, make sure it can connect to `devportal` and has privileges to create tables.

```bash
./artifacts/api_data.sh
```
To delete the mock APIs, run the following command.
```bash
./artifacts/delete_api_data.sh
```
3. Run the following command at the root folder to install the dependencies and start the developer portal.
#### 1) Update DB config (`config.json` and `secret.json`)

```bash
npm install
```
4. Run the following command to start the developer portal.:

```bash
npm start
```
Update `config.json` with your postgres DB connection details (example):

The default organization name is ACME.
This will start the webapp in the following URL : ‘[http://localhost:3000/ACME](http://localhost:3000/{orgName})’
```json
{
"db": {
"username": "postgres",
"password": "postgres",
"database": "devportal",
"host": "localhost",
"port": 5432,
"dialect": "postgres"
}
}
```

This will direct you to the organization landing page.
Make sure the **DB password** is also set in `secret.json` as `dbSecret` with the same value you use for Postgres (for example, if you used `POSTGRES_PASSWORD=postgres` in Docker, set `"dbSecret": "postgres"`).

The http://localhost:3000/ACME/apis will direct you to the api listing page.
#### 2) Create tables

Each of the api landing and tryout pages are available at the following URLs:
'http://localhost:3000/ACME/api/{apiName}'
'http://localhost:3000/ACME/api/{apiName}/tryout'
Run the schema script.

Note: the schema script drops and recreates tables, so don’t run it against a DB you can’t reset.

**Add a new third party API to the developer portal**
```bash
psql -h <HOST> -p <PORT> -U <USER> -d devportal -f artifacts/script.sql
```
#### 3) Seed sample data (optional)

Only run this section if you want sample content (ACME org + sample APIs) and the default theming assets.

From the repo root:

```bash
./artifacts/org_data.sh
./artifacts/api_data.sh
./artifacts/theme_data.sh
```

If these scripts prompt for the DB password, you can also run them non-interactively by prefixing `PGPASSWORD`:

```bash
PGPASSWORD=<DB_PASSWORD> ./artifacts/<file.sh>
```

- Configure a control plane in the developer portal.
```bash
curl --location 'http://localhost:3000/devportal/organizations/{{orgId}}/provider' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <<access_token>>' \
--data '{
If you get a permission error (e.g. `permission denied`), run:

```bash
chmod +x artifacts/*.sh
```

- `org_data.sh`: seeds a default org with handle **ACME**, creates a default view/label, and uploads the default org layout/assets into the DB.
- `api_data.sh`: seeds sample APIs and uploads sample API content/assets into the DB.
- `theme_data.sh`: uploads the default theme/styling assets into the DB (theming).

To delete the seeded APIs:

```bash
./artifacts/delete_api_data.sh
```

### Install and run

```bash
npm install
npm start
```

### Verify

Open:
- `http://localhost:3000/ACME/views/default`




## Add a third-party API (Admin APIs)

If you want to add real APIs (instead of the sample seed scripts), you can use the Devportal Admin APIs to:

- Configure a **provider** (control plane)
- Create an **API** (metadata + API definition upload)
- Upload **API landing page content** (templates/assets)

These requests typically require:

- `orgId` / `organizationID` / `apiID` (depending on the endpoint)
- `Authorization: Bearer <access_token>`

#### 1) Configure a provider (control plane)

```bash
curl --location 'http://localhost:3000/devportal/organizations/{orgId}/provider' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access_token>' \
--data '{
"name": "MuleSoft",
"providerURL": "https://anypoint.mulesoft.com/login/signin?apintent=generic"
}'
```


- Create an API in the developer portal:

The apiType values include REST, AsyncAPI, GraphQL or SOAP

The provider value should be the name of the control plane configured in the developer portal.

visibility - PUBLIC/PRIVATE

This is a multi part request containing a json with metadata related to the API and a file attachement of the api schema definition file.
``` bash
 curl --location 'http://localhost:devportal/organizations/{organizationID}/apis'

   --form 'api-metadata="{
                  "apiInfo": { 
                     "referenceID": "<UUID for the API created in WSO2 publisher>",
                     "apiName": "NavigationAPI",
                     "provider": "MuleSoft",
                     "orgName": "ACME",
                     "apiCategory": "Travel",
                     "apiDescription": "API for retrieving information about hotels and managing reservations",
                     "visibility" : "PUBLIC",
                     "visibleGroups": \["HR"\],
                     "owners" : {
                      "technicalOwner": "john",
                      "technicalOwnerEmail": "[email protected]",
                      "businessOwner" : "sam",
                      "businessOwnerEmail":"[email protected]"
                     },
                     "apiVersion" : "3.0.2",
                     "apiType" : "REST"
                  },
                  "subscriptionPolicies": [
                     {
                        "policyName": "gold"
                     },
                     {
                        "policyName": "platinum"
                     }
                  ],
                  "endPoints": {
                     "sandboxURL": "http://taxi-navigation.mnm.abc.com",
                     "productionURL": "https://taxi-navigation.mnm.abc.com"
                  }
            }"; type=application/json'
   --form 'apiDefinition=@"{apiDefinition.json}"'
```
- Upload the api landing page content.

To upload the content to be displayed on the api-landing page, create a zip file with the folder structure as follows:
``` bash
{API NAME}
└───content
   │   api-content.hbs
   │   apiContent.md
└───images
   │   icon.svg
   │   product.png
```
This is a multi part request, containing the metadata about the images in the api landing page.
This should be sent as a json key value map, with the key referring to the name in the hbs where the image is referenced and the name of the image file as the value.
For example, the key should be sent as api-icon to display the relevant image in the following img tag.
``` bash
<img src={{apiInfo.apiImageMetadata.api-icon}} class="api-card-img" alt="..." />

```
Run the following command to upload the content.
``` bash
curl --location --request POST 'http://localhost:3000/devportal/organizations/{organizationID}/apis/{apiID}/template'
     --form 'apiContent=@"{path-to-zip-file}"' \\
     --form 'imageMetadata="{
               \\"api-icon\\" : \\"navigation.jpeg\\",
               \\"api-hero\\": \\"api.svg\\"
            }"
```

Use this (https://devportal-4432.postman.co/workspace/Devportal-Workspace~9221a728-2c4b-46ec-acc3-095b9debacbc/collection/5029047-61d763dc-d7b9-4436-9a2e-94585c806943?action=share&creator=5029047) POSTMAN collection to test the API requests.
}'
```

#### 2) Create an API (metadata + definition file)

Notes:

- `apiType` can be `REST`, `AsyncAPI`, `GraphQL`, or `SOAP`
- `provider` should match the provider name configured above
- This is a multipart request: JSON metadata + an API definition file upload

```bash
curl --location 'http://localhost:3000/devportal/organizations/{organizationID}/apis' \
--header 'Authorization: Bearer <access_token>' \
--form 'api-metadata="{
\"apiInfo\": {
\"apiName\": \"NavigationAPI\",
\"provider\": \"MuleSoft\",
\"orgName\": \"ACME\",
\"apiType\": \"REST\",
\"apiVersion\": \"1.0.0\",
\"apiDescription\": \"<description>\",
\"visibility\": \"PUBLIC\"
}
}"; type=application/json' \
--form 'apiDefinition=@"{path-to-apiDefinition.json}"'
```

#### 3) Upload API landing page content (optional)

Create a zip with this structure:

```text
{API NAME}/
content/
api-content.hbs
apiContent.md
images/
icon.svg
product.png
```

Then upload it:

```bash
curl --location --request POST 'http://localhost:3000/devportal/organizations/{organizationID}/apis/{apiID}/template' \
--header 'Authorization: Bearer <access_token>' \
--form 'apiContent=@"{path-to-zip-file}"' \
--form 'imageMetadata="{
\"api-icon\": \"icon.svg\",
\"api-product\": \"product.png\"
}"; type=application/json'
```

#### Postman collection

Use this Postman collection to test the Admin API requests:

- [Devportal Postman collection](https://devportal-4432.postman.co/workspace/Devportal-Workspace~9221a728-2c4b-46ec-acc3-095b9debacbc/collection/5029047-61d763dc-d7b9-4436-9a2e-94585c806943?action=share&creator=5029047)


Loading