From f2decc1ff2f8e4f9a082d6b0641a87372155c870 Mon Sep 17 00:00:00 2001 From: Jared Galanis Date: Mon, 29 Jan 2024 13:09:41 -0500 Subject: [PATCH] refactor: update readme (#1252) --- README.md | 118 +++++++++++++----------------------------------------- 1 file changed, 27 insertions(+), 91 deletions(-) diff --git a/README.md b/README.md index 1bb60c5f..44ba8529 100644 --- a/README.md +++ b/README.md @@ -3,11 +3,7 @@ PASS is an ember application which provides a unified user interface that allow its users to deposit their manuscripts into multiple repositories as required by applicable funding agency's public access policies -PASS communicates with a Fedora repository on the backend using JSON-LD. See the -[pass-ember-adapter](https://github.com/eclipse-pass/pass-ember-adapter) for more information. -Objects persisted to Fedora are automatically indexed by Elasticsearch. See -[pass-indexer](https://github.com/eclipse-pass/pass-indexer) for more information about how this works. -Note that the indexing process is asynchronous. An object persisted to Fedora will not immediately be available in Elasticsearch. +PASS communicates with an [Elide-based API](https://github.com/yahoo/elide), [pass-core](https://github.com/eclipse-pass/pass-core), on the backend that serves json in conformance with the [JSON:API spec](https://jsonapi.org/). ## Prerequisites @@ -25,49 +21,29 @@ The `hosts` (`C:\Windows\System32\Drivers\etc\hosts` for windows, `/etc/hosts` f ## Running / Development -A docker environement which relies on a Shibboleth proxy is in .docker/. All services should -be available at https://pass.local/. +The default environment for running `pass-ui` locally is via use of [pass-docker](https://github.com/eclipse-pass/pass-docker). -- In .docker/ run `docker-compose pull` - - To start PASS with JHU assets, run `docker-compose up -d`. - - To start PASS with only a few test assets, run `docker-compose -f docker-compose.yml -f docker-compose.public.yml up -d` -- Wait for the containers to finish coming up, this could take 5-10 minutes. There will be a long pause while the `ember` container builds. When you see the "Build successful" message from `ember` and a small table listing the "Slowest Nodes" that indicates the application is ready to use. It will look similar to: +`pass-docker` can be run with `pass-ui` running inside of the docker network in its own service and docker container with these [instructions](https://github.com/eclipse-pass/pass-docker?tab=readme-ov-file#running). -``` -ember | Slowest Nodes (totalTime => 5% ) | Total (avg) -ember | ----------------------------------------------+--------------------- -ember | Babel: pass-ui (4) | 15209ms (3802 ms) -ember | broccoli-persistent-filter:EslintValid... (3) | 6654ms (2218 ms) -ember | Babel: ember-lodash (1) | 5960ms -ember | Babel: ember-data (2) | 5386ms (2693 ms) -``` +This environment is not as conducive for active development of `pass-ui` so, depending on your host machine's operating system you might be able to run `pass-ui` on your host machine outside of the docker network and use these [instructions](https://github.com/eclipse-pass/main/blob/main/docs/dev/running-pass-ui-on-your-host-machine.md) to forward traffic from the docker network to your host machine. -- The local code runs in the `ember` container, and changes in the local code will be reflected there. - - The app directory is bind mounted into the container. -- Visit your app at https://pass.local/. You will have to login as a test user. -- Run your tests at https://pass.local/app/tests -- Fedora repository is at https://pass.local/fcrepo/ -- Elasticsearch index search endpoint is at https://pass.local/es/ -- In order to remove persisted data, stop all the containers and `docker volume prune` -- Your web browser may complain about unsigned certificates, but the complaints can be ignored. +### Building for the docker environment -As an alternative to running the Ember application inside of Docker, one can run the ember test server with an environment variable to turn on the API mocking library `ember-cli-mirage` via `MIRAGE='true' ember s`. +We have GitHub automations in place to produce production builds at during a release. If you want to development build for local testing, you can use the `build.sh` script, specifying a `.env` file: -### Test users +```sh +./build.sh ../pass-docker/.env +``` -See [https://github.com/eclipse-pass/pass-docker/blob/master/README.md#shibboleth-users] for a list of test users. Each has a password of `moo`. +This script will remove any existing files in `dist/`, do an Ember dev build, and create a new pass-ui Docker image with the `:latest` tag -### Configuration +### Test users -The configuration for the docker environment occurs in .env. See documentation on the individual -components for configuration options. +Refer to the LDAP service in `pass-docker` for [a list](https://github.com/eclipse-pass/pass-docker/blob/main/ldap/jhu/users.ldif) of test users. Each has a password of `moo`. -The pass-ui application configures the Fedora adapter uses these environment variables. -There are also defaults specified in config/environment.js. They tell the adapter where Fedora -and Elasticsearch are and generally will not need to be modified during development. +### Configuration -In order to prevent an Authorization header being sent to Fedora and Elasticsearch, -set FEDORA_ADAPTER_USER and FEDORA_ADAPTER_PASSWORD to empty strings. +The configuration for the docker environment occurs in the `pass-docker` [.env](https://github.com/eclipse-pass/pass-docker/blob/main/.env). A list of environment variables related to `pass-ui`, and other services, can be found there or in other [override .env files](https://github.com/eclipse-pass/pass-docker/blob/main/.eclipse-pass.local_env). The application also gets "branding" configuration from a `config.json` file, with a default implementation found in the `public/` directory, which is automatically made available by default at `/app/config.json`. @@ -76,18 +52,16 @@ The application also gets "branding" configuration from a `config.json` file, wi ```js { "branding": { - "homepage": "https://example.com", - "logo": "/app/fullSizeLogo.png", // Default asset found in public/ dir - "favicon": "/app/favicon.png", // Default asset found in public/ dir - "stylesheet": "/app/branding.css", // Default asset found in public/ dir which provides base styles - "overrides": "/app/branding-overrides.css", // Overrides to the default base styles + "homepage": "https://www.eclipse.org/org/foundation/", + "logo": "ef/eclipse_foundation_logo_wo/EF_WHT-OR_png.png", + "favicon": "favicon.ico", + "stylesheet": "/app/branding.css", + "overrides": "/app/branding-overrides.css", "pages": { - "contactUrl": "", // If you provide a branded page with contact info - "aboutUrl": "", // If you provide a branded About page for PASS - "faqUrl": "", // If you provide a branded FAQ page + "showPagesNavBar": false }, "error": { - "icon": "", // Error icon to display on the application's error page + "icon": "/app/error-icon.png" } } } @@ -95,36 +69,9 @@ The application also gets "branding" configuration from a `config.json` file, wi The base theme styles can be found in `branding.css`. There are default fallback styles which can be overridden to customize the appearance of the UI. It is recommended to override these styles through a `branding-overrides.css` file. An example of these overrides to the base styles can be found [here](https://github.com/eclipse-pass/pass-ui/blob/main/public/branding-overrides.css). -### Environment Variables - -| Name | Description | Default value | -| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | -| EMBER_APP_ROOT | URL path of the application | `/app/` | -| EMBER_HOST | URL host of the application | `http://localhost:8080` | -| PASS_API_URL | URL host (plus port) of backend API | `http://localhost:8080` | -| PASS_API_NAMESPACE | URL path prefix for backend API | `api/v1` | -| STATIC_CONFIG_URL | URL to find the UI's branding configuration (config.json). There is a default config bundled with the application, which can be loaded at this variable's default value | `/app/config.json` | -| USER_SERVICE_URL | URL of the pass user service | `/pass-user-service/whoami` | -| SCHEMA_SERVICE_URL | URL of the pass metadata schema service | `/schemaservice` | -| DOI_SERVICE_URL | URL of the pass DOI service | `/doiservice/journal` | -| DOI_METADATA_SCHEMA_URI | URL of the DOI metadata schema | `https://eclipse-pass.github.io/metadata-schemas/jhu/global.json` | -| POLICY_SERVICE_URL | URL of the pass policy service (no longer supported) | `/policyservice` | -| POLICY_SERVICE_POLICY_ENDPOINT | URL of the pass policy service policies function | `/policyservice/policies` | -| POLICY_SERVICE_REPOSITORY_ENDPOINT | URL of the pass policy service repositories function | `/policyservice/repositories` | -| MANUSCRIPT_SERVICE_LOOKUP_URL | URL of the pass 'download' service's lookup function. This will lookup available open access manuscripts for a given DOI | `/downloadservice/lookup` | -| MANUSCRIPT_SERVICE_DOWNLOAD_URL | URL of the pass 'download' service's download function. Currently unused? | `/downloadservice/download` | - -### Using ember in the container. - -Login to the ember container with `docker exec -it ember /bin/sh`. -Then run ember with `./node_modules/ember-cli/bin/ember`. -This can be useful for adding and updating dependencies. -You can run also run tests, but you may have to install other dependencies such as google-chrome. - -### Running ember locally - -If you wish, you may install ember locally. The application will not be able to run due to the need to access various web services, -but running tests on the command line can be useful. See documentation at [ember.js](https://emberjs.com/). +### Testing + +To run the Ember.js unit/integration/acceptance tests in this repository you can run one of the scripts in the [package.json](https://github.com/eclipse-pass/pass-ui/blob/main/package.json) or simply run the Ember development server via `ember s` and visit `http://pass.local/app/tests`. ### Linting @@ -132,22 +79,11 @@ This project uses `es-lint`, `ember-template-lint` and `prettier` to enforce sty This project uses (husky)[https://github.com/typicode/husky] to run a command from (lint-staged)[https://github.com/okonet/lint-staged] to run `es-lint --fix` and `prettier --write` over the staged files in a pre-commit hook. If you are unable to make a commit it might be because either one or both of these commands has failed. Check the output in the terminal for what failures have occurred. -There are also scripts defined in the `package.json` you can run to manually lint check the project. - -- `yarn lint` -- `yarn lint:fix` -- `yarn lintt:hbs` -- `yarn link:hbs:fix` - -### Building - -We have GitHub automations in place to produce production builds at during a release. If you want to development build for local testing, you can use the `build.sh` script, specifying a `.env` file: +There are also scripts defined in the [package.json](https://github.com/eclipse-pass/pass-ui/blob/main/package.json) you can run to manually lint check the project. -```sh -./build.sh ../pass-docker/.env -``` +### CI -This script will remove any existing files in `dist/`, do an Ember dev build, and create a new pass-ui Docker image with the `:latest` tag +Both tests and linting will be run by the [ci.yml workflow](https://github.com/eclipse-pass/pass-ui/blob/main/.github/workflows/ci.yml) in Github on opening of pull requests and pushes to the `main` branch. ## Further Reading / Useful Links