Pages Editor

A customized Payload CMS editor for creating and managing federal websites.

Initial Goals

Content Editors can:

• Edit via WYSIWIG Editor
• Avoid login through Github
• Perform basic user management and editorial workflow functions

Second Goals

• Basic asset management
• Access Modules/Blocks/Pre-configured units of content
• Edit non-Post pages

Development

Running Locally

docker compose build
docker compose run app npm ci
docker compose run app npm run seed
docker compose up

After this, the editor is available at localhost:3000/admin; the first load will take a few seconds while the app is compiled.

The database is seeded with the following for local development:

• Three sites, one of which is a "dummy" site for admins
• At least five users:
  • [email protected]: Global admin representing a Pages operator
  • [email protected], [email protected]: Website managers with access to one site each.
  • [email protected], [email protected]: Website users with access to one site each.
  • By default, sites create a bot user with read-only access to site data.
  • To login as a user, use the password password

If the database schema is changed in response to changes in the collections/globals, the development may prompt to accept certain changes (e.g. Accept warnings and push schema to database?). Developers can attach to the development server via:

docker attach <container_name> # pages-editor-app-1 by default

To detach without exiting the process: ctrl + p, then ctrl + q

Infrastructure Notes

• Based on the Payload CMS website template
• Written as a mult-tenant application similar to the Payload example but customized for certain necessary patterns:
  • Full tenant isolation (the payload example allows users to view the tenant access of other users)
  • Site managers can add users. Attempting to add existing users alters their sites property rather than erroring.
  • Custom site/roles display (ongoing)
  • ...
• Relies on pages-site-gantry for live previewing

Cloud Foundry Setup

This repository's CI deploys the pages-editor-((env)) application and pages-site-gantry deploys the preview application. There are four other services which are manually created per-environment:

name	service	plan	notes
pages-editor-((env))-rds	aws-rds	micro-psql	Primary database
pages-editor-((env))-deployer	cloud-gov-service-account	space-deployer	Create account. Add these credentials to cred-hub
pages-editor-((env))-auth	cloud-gov-identity-provider	oauth-client	Create the service. Add these credentials to pages-editor-((env))-creds
pages-editor-((env))-creds	user-provided		Credentials here are captured in the .profile script for different applications
pages-editor-((env))-s3	pages-s3	basic-vpc	Used for storing site information to be passed on to Concourse

Each environment has a network access policy for sending email per these instructions (make sure to specify additional ports if needed to match the EMAIL_HOST environment variable)

Test framework and structure

DB Tests

We currently run a series of access controls tests against our database using various users. Access control is implement via Payload properties and custom functions we've written in src/access. A requirement of this application is that site data is made available only to appropriate users; these tests are essential to making that guarantee. Tests are located at src/collections/**/access.test.ts

Tests are run with vitest via:

npm run test

We make extensive use of vitest context and fixtures in our tests. Important notes:

• Each test runs as a separate transaction: all fixtures are scoped to that transaction, the transaction id is passed to the test, and all DB operations should use that transaction id to guarantee they are operating on the correct data and are correctly removed at the end of the test.

• The transaction id and sites are automatic fixtures and are available for every test. For other fixtures, ensure that the fixture variable is passed as part of the destructed test context for it to be initialized. E.g.

    ```ts
    test('my test needs posts', async ({ tid, posts }) => ...
    ```
  

  Currently available fixtures are shown at test/utils/context.types.ts.

  • These fixtures can be overwritten or modified for a given describe block by using test.scoped. Modified values will be passed down to any dependent fixtures (e.g. defaultUserRole will update testUser accordingly). Note that this is only available in a pre-release version of vitest ("^3.1.0-beta.2").

• The test database is cleared (test/utils/globalSetup.ts) before and after each test-suite run to ensure accurate fixtures.

UI Tests

TBD

API Tests

TBD