{"id":39076032,"url":"https://github.com/cloud-gov/cg-ui","last_synced_at":"2026-01-17T18:26:44.524Z","repository":{"id":248595976,"uuid":"747343852","full_name":"cloud-gov/cg-ui","owner":"cloud-gov","description":"New UI for cloud.gov customers to manage their CF apps.","archived":false,"fork":false,"pushed_at":"2025-10-02T21:56:58.000Z","size":3512,"stargazers_count":3,"open_issues_count":91,"forks_count":1,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-10-02T23:31:06.381Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cloud-gov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-01-23T18:38:20.000Z","updated_at":"2025-06-18T16:52:35.000Z","dependencies_parsed_at":"2025-06-17T17:35:40.771Z","dependency_job_id":null,"html_url":"https://github.com/cloud-gov/cg-ui","commit_stats":null,"previous_names":["cloud-gov/cg-ui"],"tags_count":1,"template":false,"template_full_name":"cloud-gov/.github","purl":"pkg:github/cloud-gov/cg-ui","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud-gov%2Fcg-ui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud-gov%2Fcg-ui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud-gov%2Fcg-ui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud-gov%2Fcg-ui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloud-gov","download_url":"https://codeload.github.com/cloud-gov/cg-ui/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloud-gov%2Fcg-ui/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28515473,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T17:57:59.192Z","status":"ssl_error","status_checked_at":"2026-01-17T17:57:52.527Z","response_time":85,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-17T18:26:43.781Z","updated_at":"2026-01-17T18:26:44.506Z","avatar_url":"https://github.com/cloud-gov.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cloud.gov UI prototype\n\nThis is a prototype for a future Cloud.gov user interface.\n\n## Getting started with local development\n\n### Step 1: Prepare your environment\n\n#### Node\n\n[Install node 20.x](https://nodejs.org/en/download/) on your machine. Check [`.nvmrc`](.nvmrc) for the app's current version.\n\n#### ZScaler\n\nIf your environment uses ZScaler, you must make Node aware of your ZScaler certificate so you can install packages via npm. If ZScaler is not active in your environment, you may skip this part.\n\nOutput the certificate in pem format. Place the pem in a stable location you can refer to repeatedly.\n\n```bash\nsecurity find-certificate -a -c zscaler -p \u003e [path_to_cert]/zscaler_root_ca.pem\n```\n\nEdit a file that will execute when you open a new terminal session. For example, `~./zshrc` or `~./bashrc` or similar. Load the pem as a variable that Node will read:\n\n```bash\nexport NODE_EXTRA_CA_CERTS=[path_to_cert]/zscaler_root_ca.pem\n```\n\n#### Dependencies\n\nOpen a new shell, clone this repository, and install the dependencies:\n\n```bash\nnpm install\n```\n\nNext, [install the Cloud Foundry command line tool](https://docs.cloudfoundry.org/cf-cli/install-go-cli.html). On mac, you can run:\n\n```bash\nbrew install cloudfoundry/tap/cf-cli@8\n```\n\n### Step 2: Log into your Cloud.gov account\n\nAsk a member of the Cloud.gov team to grant your user access to the cloud development environment. You may choose instead to use your regular (production) cloud.gov account, but be aware that __any actions you take in the app, such as deleting spaces or apps, will affect your cloud.gov applications and services.__\n\nOnce you have a development account, log into the CF CLI. Follow the prompts to authenticate:\n\n```bash\n# log into development\ncf login -a api.dev.us-gov-west-1.aws-us-gov.cloud.gov --sso\n\n# log into production (not recommended)\ncf login -a api.fr.cloud.gov --sso\n```\n\nYou do not need to target an organization or space.\n\n### Step 3: Run a local user accounts and authentication (UAA) server\n\nUsers will need to authenticate through UAA in order to view the application. A real UAA flow can't be done locally, because UAA can't whitelist `localhost`. So in local development, we simulate authentication in two ways:\n\n1) **By running a local UAA server** - This login flow provides fake `authsession` cookie data. The presence of this cookie is what allows you to visit authenticated pages when navigating the app.\n2) **By setting CloudFoundry data in our environment file** - Because local UAA returns fake data, we need to obtain real CF credentials through the CF CLI and keep them in `.env.local`. This allows you to get real CloudFoundry API data. (Handled in steps 4 and 5.)\n\nSee the [uaa-docker README](uaa-docker/README.md) for set up instructions.\n\nIn another shell, start the UAA container:\n\n```bash\ncd uaa-docker\n# follow instructions to build before running up\ndocker compose up\n```\n\nUse credentials found in `uaa-docker/uaa.yml` to log in.\n\n### Step 4: Configure the application\n\nCopy the example `.env.example.local` file. Do not check `.env.local` into source control.\n\n```bash\ncp .env.example.local .env.local\n```\n\nYou do not need to change anything about this file for local development unless you logged into your production cloud.gov account during the previous step.\n\n```bash\n# change this line if you are using production\nCF_API_URL=https://api.fr.cloud.gov/v3\n```\n\nFor certain pages, you'll also need to set your `CF_USER_ID`. This is normally returned from UAA and placed in the `authsession` cookie, but when working locally, you'll need to obtain this from your CloudFoundry environment (like by running `cf curl '/v3/users'` or by running `cf oauth-token` and decoding the returned JWT token).\n\nNote: the variable `CF_API_TOKEN` is not yet populated. That's okay! Continue to the next step to set it.\n\n### Step 5: Run the app!\n\nStart the app with the `dev-cf` command:\n\n```bash\nnpm run dev-cf\n```\n\nThis will fetch your local cloud foundry token from the CF CLI tool and use it to start the app, giving your user permission to access and manipulate cloud foundry resources through the UI.\n\nVisit `localhost:3000` to check it out!\n\n#### Troubleshooting and dev eccentricities\n\nDue to developing locally against a \"real\" environment, we have to play by the rules of the CF CLI. This means that our token expires every 15 minutes or so, and we also need to reauthenticate every 24 hours.\n\nThe `dev-cf` command runs a token refresh every 14 and a half minutes, provided you're still authenticated. If you start getting 401 errors, reauthenticate with CF CLI and GSA PreProd as described in step 2, then restart your application to get a new token. \n\n### Step 6: Optional stretch goals\n\nThe above steps are enough to get most people up and running, but our app has more bells and whistles! Consider yourself good to go unless if you plan to do any of the following:\n\n- running the test suite\n- working on the logging in flow\n- developing something related to user access information\n- in need of a database\n\n#### S3 user information\n\nThis application relies on an s3 bucket to pull information about a user's last access date and their account status (active vs inactive). This bucket is populated by the [uaa-bot](https://github.com/cloud-gov/uaa-bot) and is only available in the development environment. If access is not hooked up, you will simply see \"no user information\" in the UI.\n\nCreate a new service key for your targeted org and environment. Name the key something descriptive enough that you can identify it again. For example, `cg-ui-storage-key`.\n\n```bash\ncf create-service-key cg-ui-storage [name-of-your-key]\n```\n\nPull down the key (this contains sensitive information):\n\n```bash\ncf service-key cg-ui-storage [name-of-your-key]\n```\n\nYou are interested in these parts of the key:\n\n```\n{\n  \"access_key_id\": \"...\",\n  \"bucket\": \"...\",\n  \"region\": \"...\",\n  \"secret_access_key\": \"...\"\n}\n```\n\nCopy the values into your `.env.local` file for the variables `S3_ACCESS_KEY_ID`, `S3_ACCESS_KEY_SECRET`, `S3_BUCKET`, AND `S3_REGION`.\n\nYou can keep the key around between development sessions, but you may wish to rotate it or delete it when you are no longer using it:\n\n```bash\ncf delete-service-key cg-ui-storage [name-of-your-key]\n```\n\n#### The database\n\nFollow the steps in the [cgui-db-docker README](cgui-db-docker/README.md) to set up a postgres db in docker. This database is only a proof-of-concept for our application at the moment, but is needed if you will be running the full test suite.\n\nStart the container (note, the command may be `docker-compose` on older installs):\n\n```bash\ncd cgui-db-docker\ndocker compose build\ndocker compose up\n```\n\n\n### Step 7: Testing\n\nTo run the entire unit test suite, you will need to start the docker database container:\n\n```bash\ncd cgui-db-docker\ndocker compose up\n```\n\nRun the suite:\n\n```bash\nnpm test\n```\n\nTo run test files matching certain text (one example):\n\n```bash\nnpm test -- serverside\n```\n\n#### Integration testing\n\nWe have one test that runs against the s3 bucket to test that updates to the AWS libraries have not broken the connection. This test runs locally and is not part of the CI pipeline. To run this test, set up a local-only test environment file. This file should not be tracked in version control:\n\n```bash\ncp .env.test.example.local .env.test.local\n```\n\nThen, if you have not already, set up a [s3 service key](#s3-user-information). Copy the values into `.env.test.local`.  To run the test:\n\n```bash\nnpm run test:integration\n```\n\n### Step 8: Committing\n\n#### Preparing your code\n\nYou can optionally set up the repository with a pre-commit hook to scan files you have just staged for linting / prettifying:\n\n```bash\nnpm run setup-precommit\n```\n\nIf you prefer, you may run these utilities manually instead:\n\n```bash\nnpm run lint\n\nnpm run format\n# to alter files automatically\nnpm run format:fix\n```\n\nYou may also wish to test that the next application is building before you commit and push:\n\n```bash\nnpm run build\n```\n\nEslint configurations are found in [.eslintrc.json](.eslintrc.json). Prettier configurations are found in [.prettierrc.json](.prettierrc.json).\n\n#### Signing your commits\n\nCloud.gov requires any commits to this repo to be signed with a GPG key. [You will need to set up commit signing before the first time you contribute](https://docs.google.com/document/d/11UDxvfkhncyLEs-NUCniw2u54j4uQBqsR2SBiLYPUZc/edit) :closed_lock_with_key:.\n\n#### Scanning for secrets\n\nCloud.gov requires that contributors have the [caulking tool](https://github.com/cloud-gov/caulking) installed and running on their machines. Follow the instructions to install caulking and confirm that `make audit` passes all checks.\n\n## Step 9: Deploying\n\nThis application is deployed to the cloud.gov development environment automatically when changes are merged into the main branch. Deployment is managed via Concourse CI (see the `ci` directory).\n\nSee the developer documentation for instructions to [manually deploy the application](docs/dev-practices/manual-deploy.md).\n\n## Team practices\n\n### Working with USWDS\n\nOur team keeps custom CSS/SASS to a minimum and takes a [utilities-first](https://designsystem.digital.gov/utilities/) approach.\n\nPlease see our [developer guidelines](docs/dev-practices/USWDS.md) about this approach, how USWDS is integrated into our application, and steps to take when upgrading.\n\n### File conventions\n\nWe prioritize named imports, TypeScript, and Pascal Case component names throughout our application. Read more about our [file conventions](docs/dev-practices/file-conventions.md).\n\n### Application structure\n\nNext.js has few opinions about how to structure applications. We have chosen to use an MVC (Model View Controller)-like pattern.\n\nSee our [architecture](docs/dev-practices/architecture.md) documentation for information about each of the layers and how we are using them.\n\n### Architectural decision records and explainers\n\nWe keep Architectural Decision Records (ADRs) to explain decisions we have made and alternatives we considered. You may find them in the [adrs](docs/adr/README.md) directory.\n\nWhen we come across concepts that are initially confusing or required significant time to understand, we have created [explainers](docs/explainers/README.md) to capture our newly acquired knowledge.\n\n## Updating dependencies\n\n### Updating Node\n\nThe Node version should be updated in the following places:\n\n1. [.nvmrc](.nvmrc) which controls the version for cloud builds\n1. [Github workflow containers](.github/workflows/pull-request.yml) `NODE_VERSION` which controls the version in Github action containers\n1. [package.json](package.json) under `engines` to specify which version(s) our app works with\n1. [Concourse docker-compose](ci/docker/docker-compose.yml) and [pipeline](ci/pipeline.yml)\n\n### Updating USWDS\n\nSee the [USWDS](docs/dev-practices/USWDS.md) documentation for more information about how to update USWDS and its assets.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloud-gov%2Fcg-ui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloud-gov%2Fcg-ui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloud-gov%2Fcg-ui/lists"}