Skip to content

Commit

Permalink
refactor: update readme (#1252)
Browse files Browse the repository at this point in the history
  • Loading branch information
@jaredgalanis
jaredgalanis authored Jan 29, 2024
1 parent b71c883 commit f2decc1
Showing 1 changed file with 27 additions and 91 deletions.
118 changes: 27 additions & 91 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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`.

Expand All @@ -76,78 +52,38 @@ 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"
}
}
}
```

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

This project uses `es-lint`, `ember-template-lint` and `prettier` to enforce style decisions and code formatting. You may consider installing [an integration tool](https://prettier.io/docs/en/editors.html) for your editor of choice.

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

Expand Down

0 comments on commit f2decc1

Please sign in to comment.