{"id":23143743,"url":"https://github.com/digitalinteraction/catalyst-webapp","last_synced_at":"2025-04-04T12:15:00.087Z","repository":{"id":49604920,"uuid":"173985227","full_name":"digitalinteraction/catalyst-webapp","owner":"digitalinteraction","description":"A Vue web app for browsing, searching and viewing Not-Equal Catalyst projects","archived":false,"fork":false,"pushed_at":"2021-08-31T12:36:09.000Z","size":2603,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-09T22:11:19.952Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://catalyst.not-equal.tech/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/digitalinteraction.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-03-05T16:50:00.000Z","updated_at":"2024-11-08T12:31:40.000Z","dependencies_parsed_at":"2022-09-15T02:12:38.881Z","dependency_job_id":null,"html_url":"https://github.com/digitalinteraction/catalyst-webapp","commit_stats":null,"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalinteraction%2Fcatalyst-webapp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalinteraction%2Fcatalyst-webapp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalinteraction%2Fcatalyst-webapp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/digitalinteraction%2Fcatalyst-webapp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/digitalinteraction","download_url":"https://codeload.github.com/digitalinteraction/catalyst-webapp/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247174467,"owners_count":20896078,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":"2024-12-17T15:14:08.554Z","updated_at":"2025-04-04T12:15:00.059Z","avatar_url":"https://github.com/digitalinteraction.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Catalyst | Vue WebApp\n\nThis is the repo for Not-Equal Catalyst's frontend webapp.\nIt is a [Vue.js](https://vuejs.org/) project written in JavaScript,\n[pug](https://pugjs.org) and [sass](https://sass-lang.com/) and deployed through [Docker](https://www.docker.com/) where it is served using [express](https://expressjs.com/) and [vue-ssr](https://ssr.vuejs.org/).\n\n[What is Not-Equal Catalyst?](https://github.com/unplatform/catalyst-about)\n\n\u003c!-- toc-head --\u003e\n\n## Table of contents\n\n- [Table of Contents](#table-of-contents)\n- [Usage](#usage)\n  - [Environment variables](#environment-variables)\n  - [Categorisation file](#categorisation-file)\n  - [Filters file](#filters-file)\n  - [Trello key-values](#trello-key-values)\n- [Development](#development)\n  - [Setup](#setup)\n  - [Regular use](#regular-use)\n  - [Irregular use](#irregular-use)\n  - [Commits](#commits)\n  - [Code Structure](#code-structure)\n  - [Webpack build](#webpack-build)\n  - [Code formatting](#code-formatting)\n- [Deployment](#deployment)\n  - [Building the image](#building-the-image)\n- [Future work](#future-work)\n\n\u003c!-- toc-tail --\u003e\n\n## Usage\n\nThis repo has a Docker image which you can use to run the Vue SSR server which serves the webapp assets.\nThe server runs on `8080` inside the container, so you'll need to map that for external traffic.\n\nHere's an example with docker-compose:\n\n```yml\nversion: '3'\n\nservices:\n  web-ui:\n    image: ghcr.io/digitalinteraction/catalyst-webapp\n    ports:\n      - 8080:8080\n    environment:\n      PUBLIC_URL: https://catalyst.not-equal.tech\n      API_URL: https://api.catalyst.not-equal.tech\n      REDIS_URL: redis://your_redis_url\n```\n\n\u003e Get the [latest version](https://github.com/digitalinteraction/catalyst-webapp/pkgs/container/catalyst-webapp)\n\n### Environment variables\n\nThere are some required environment variables, shown below.\n\n| Variable   | Description                                           |\n| ---------- | ----------------------------------------------------- |\n| REDIS_URL  | The redis connection uri                              |\n| PUBLIC_URL | Where the app is, used for generating opengraph meta  |\n| API_URL    | Where the api is, passed into the webapp through vuex |\n\nThere are some optional variables too:\n\n| Variable       | Description                                                   |\n| -------------- | ------------------------------------------------------------- |\n| APP_NAME       | Set the app's name, used in opengraph and as the window title |\n| APP_INFO       | Set the app's description, used in opengraph                  |\n| TWITTER_HANDLE | The twitter handle of the project (used in opengraph)         |\n| CUSTOM_STYLES  | A url to a custom css file to load                            |\n\nThere are files you can override with bind-mounts.\n\n| Path                                 | File                                                   |\n| ------------------------------------ | ------------------------------------------------------ |\n| `/app/public/favicon.png`            | The site's favicon                                     |\n| `/app/public/opengraph.png`          | The site's opengraph image e.g. for tweets             |\n| `/app/public/config/categories.json` | Categorisation file, [see below](#categorisation-file) |\n| `/app/public/config/filters.json`    | Filters file [see below](#filters-file)                |\n| `/app/public/categories/*`           | Custom category images (map to from categories.json)   |\n\n### Categorisation file\n\nThis file is used to define how card's are categorised in the interface.\nYou can specify what tags to map a category to and how that category looks.\nIt should be a JSON object like:\n\n```json\n{\n  \"algorithms\": {\n    \"id\": \"algorithms\",\n    \"name\": \"Algorithmic Social Justice\",\n    \"image\": \"algorithms.png\",\n    \"color\": \"red\",\n    \"match\": [\"call:algorithmic-social-justice\"]\n  }\n}\n```\n\n- `id` should be a unique identifier for the category\n- `name` is the name it is presented as\n- `image` will resolve to files inside `/app/public/categories`\n- `color` can be `red`, `yellow`, `blue` or `green`\n- `match` is a set of labels that mean a card is part of this category\n- You can also set a `_fallback` category which is used when a category didn't match\n\n### Filters file\n\nThis file is used to define the filters that you can use in the interface.\nIt should be a JSON array in the form:\n\n```json\n[\n  {\n    \"id\": \"call\",\n    \"title\": \"Call for proposal\",\n    \"prefix\": \"call:\",\n    \"logic\": \"or\"\n  }\n]\n```\n\n- `id` should be a unique identifier for the filter\n- `title` is how the filter is presented in the interface\n- `prefix` is a prefix for tags which this filter by\n- `logic` is how the filter should behave, either `and` or `or`\n\n### Trello key-values\n\nYou can also set these vaules from the Trello `CONTENT_LIST_ID`\nand they will tweak bits of text in the interface.\nThese are all optional.\n\n| Key                  | Usage                                           |\n| -------------------- | ----------------------------------------------- |\n| `[home.title]`       | The title on the homepage, shown after the hero |\n| `[home.strapline]`   | The strapline on the homepage, in the hero      |\n| `[home.searchLabel]` | The label next to the search field              |\n| `[home.noMatches]`   | A label when filtering returns no responses     |\n| `[home.noResponses]` | A label when there are no responses at all      |\n| `[about.title]`      | The title of the about page                     |\n| `[about.subtitle]`   | The subtitle of the about page                  |\n| `[about.long]`       | The content of the about page                   |\n| `[about.short]`      | The info displayed next to a project detail     |\n| `[notFound.title]`   | The title of the not found page                 |\n| `[notFound.message]` | The message of the not found page               |\n\n## Development\n\n### Setup\n\nTo develop on this repo you will need to have [Docker](https://www.docker.com/) and\n[node.js](https://nodejs.org) installed on your dev machine and have an understanding of them.\nThis guide assumes you have the repo checked out and are on macOS, but equivalent commands are available.\nYou will also need a Trello account which is used to pull the data from.\n\nYou'll only need to follow this setup once for your dev machine.\n\n```bash\n# Install dependancies\nnpm install\n\n# Setup your client environment\ncp .env.example .env.local\n\n# Follow these instructions to get your Trello credentials\nopen https://github.com/unplatform/catalyst-trello-scraper#setup\n\n# Setup your server environment\ncp .env.server.example .env.server.local\n```\n\n### Regular use\n\nThese are the commands you'll regularly run to develop the API, in no particular order.\n\n```bash\n# Start up a redis instance, fetch projects and serve them with the api\n# -\u003e Run this in a new terminal tab\n# -\u003e Stop this with a Ctrl+C\n# -\u003e See `docker-compose.yml` for how it works\ndocker-compuse up\n\n# Compile and run the vue-cli-service's server\n# -\u003e Internally uses webpack to transpile assets to html, css \u0026 js\n# -\u003e Stop this with a Ctrl+C\n# -\u003e Only runs the client, no ssr yet\nnpm run serve\nopen http://localhost:8080\n```\n\n### Irregular use\n\nThese are commands you might need to run but probably won't, also in no particular order.\n\n```bash\n# Generate the table of contents for this readme\n# -\u003e It'll replace content between the toc-head and toc-tail HTML comments\nnpm run gen-readme-toc\n\n# Manually lint code with TypeScript's `tsc`\nnpm run lint\n\n# Manually format code\n# -\u003e This repo is setup to automatically format code on git-push\nnpm run prettier\n\n# Manually build all assets (html, css, js \u0026 images)\n# -\u003e Runs both the other build commands together\n# -\u003e Writes to dist/\nnpm run build\n\n# Manually build the assets for the client\nnpm run build:client\n\n# Manually build the assets for the server (creates a vue-ssr-server-bundle-json)\nnpm run build:client\n\n# Run the ssr server\n# -\u003e Requires .env.server.local to be setup\n# -\u003e Stop this with a Ctrl+C\n# -\u003e Just runs the server, no file watching or restarting\nnode server/index.js\n```\n\n### Commits\n\nAll commits to this repo must follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).\nThis ensures changes are structured and means the [CHANGELOG.md](/CHANGELOG.md) can be automatically generated.\n\nThis standard is enforced through a `commit-msg` hook using [yorkie](https://www.npmjs.com/package/yorkie).\n\n### Code Structure\n\n| Folder         | Contents                                          |\n| -------------- | ------------------------------------------------- |\n| dist           | Where the html, css, js \u0026 img assets are built to |\n| node_modules   | Where npm's modules get installed into            |\n| public         | Unmodified assets, served directly to the client  |\n| server         | The source code for the vue-ssr express server    |\n| src            | The source code for the web app                   |\n| src/assets     | Image assets that are built into the app          |\n| src/components | Reusable Vue components                           |\n| src/data       | Static information for the web app                |\n| src/sass       | Custom styles written in sass                     |\n| src/views      | The app's views, components which are routed to   |\n\n### Webpack build\n\nThis repo uses [vue-cli-service](https://cli.vuejs.org/) to handle most webpack configuration,\nincluding `babel`, `post-css` and processing `.vue` components.\nThere are some tweaks to the defaults, these can be found in [vue.config.js](/vue.config.js) and are detailed below.\n\n- [shared.sass](/src/shared.sass) is automatically imported for each Vue component's `\u003cstyle\u003e` tags (with variables and mixins)\n- `process.env.VUE_APP_VERSION` is set to the package.json version\n- It adds `vue-svg-loader`\n- It sets up the required things for vue-ssr\n\n### Code formatting\n\nThis repo uses [Prettier](https://prettier.io/) to automatically format code to a consistent standard.\nThis works using the [husky](https://www.npmjs.com/package/husky)\nand [lint-staged](https://www.npmjs.com/package/lint-staged) packages to\nautomatically format code whenever you commit code.\nThis means that code that is pushed to the repo is always formatted to a consistent standard.\n\nYou can manually run the formatter with `npm run prettier` if you want.\n\nPrettier is slightly configured in [.prettierrc.yml](/.prettierrc.yml)\nand also ignores files using [.prettierignore](/.prettierignore).\n\n## Deployment\n\n### Building the image\n\nThis repo uses a [GitLab CI](https://about.gitlab.com/product/continuous-integration/)\nto build a Docker image when you push a git tag.\nThis is designed to be used with the `npm version` command so all docker images are [semantically versioned](https://semver.org/).\nThe `:latest` docker tag is not used.\n\nThis job runs using the [.gitlab-ci.yml](/.gitlab-ci.yml) file which\nruns a docker build using the [Dockerfile](/Dockerfile)\nand **only** runs when you push a [tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging).\n\nIt pushes these docker images to the GitLab registry of the repo.\nA slight nuance is that it will replace a preceding `v` in tag names, formatting `v1.0.0` to `1.0.0`.\n\n```bash\n# Generate a new release\n# -\u003e Generates a new version based on the commits since the last version\n# -\u003e Generates the CHANGELOG.md based on those commits\n# -\u003e There is a \"preversion\" script to lint \u0026 run tests\nnpm run release\n\n# Push the new version\n# -\u003e The GitLab CI will build a new docker image for it\ngit push --follow-tags\n```\n\n## Future work\n\n- n/a\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigitalinteraction%2Fcatalyst-webapp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdigitalinteraction%2Fcatalyst-webapp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdigitalinteraction%2Fcatalyst-webapp/lists"}