Quarterback is a service to manage tracking of changes and their related metadata for Manuscripts app. It also includes a prototype implementation for collaboration using Yjs.
You need Docker & Docker Compose.
docker-compose up -d api postgres
First you should check you have Node.js >=16 installed: node -v. If not, I recommend using nvm. This is needed for the ES modules and other new features.
This project uses Docker and Docker Compose. You should have at least version 17 / 1.13 installed: docker -v. Then you might have to add this repository to the shared folders in your Docker settings (macOS or Windows - not Ubuntu though) eg Preferences > Resources > File sharing in macOS Docker Desktop.
Also this project imports https://gitlab.com/mpapp-public/manuscripts-manuscript-editor https://gitlab.com/mpapp-public/manuscripts-manuscript-transform (now https://github.com/Atypon-OpenSource/manuscripts-schema havent migrated / removed since still works & not urgent) and https://github.com/Atypon-OpenSource/manuscripts-style-guide as git submodules which you should checkout with: git submodule update --init --recursive
NOTE: it is a good idea to run git submodule update --remote once in a while incase the quarterback-integration branches in the git submodules have been updated. Incase a submodule was deleted it does not seem to update itself automatically and a manual removal is needed. Should not happen in general but be aware.
For running the Postgres scrips you need to install psql eg: install postgresql-client-common postgresql-client
examples-packages contain a prototype setup with Manuscript editor that closely follows the track changes implementation in LeanWorkflow. It also includes an example Yjs server that uses Redis persistence.
- Checkout Git submodules if you haven't already:
git submodule update --init --recursive - Install all dependencies:
pnpm i - Start the databases:
docker-compose up -d postgres redis - Initialize example database:
./scripts.sh db:init-ex - Copy the environment variables:
cp ./examples-packages/api/.example-env ./examples-packages/api/.env && cp ./examples-packages/collab/.example-env ./examples-packages/collab/.env && cp ./examples-packages/db/.example-env ./examples-packages/db/.env && cp ./examples-packages/client/.example-env ./examples-packages/client/.env - Migrate the database:
pnpm --filter @manuscripts/examples-track-db migrate - And seed it with test data:
pnpm --filter @manuscripts/examples-track-db seed - Build the external manuscripts packages:
pnpm ex:manNOTE: their build throws compilation errors but they should compile nonetheless, incase something goes missing from the bundles you might have to run the builds separately egpnpm --filter @manuscripts/manuscript-transform build:cjs - Start API in a terminal session:
pnpm ex:api - Start Yjs server in a terminal session:
pnpm ex:collab - Build / watch DB types & track-changes-plugin:
pnpm ex:utils - Build / watch editor and its extensions:
pnpm ex:editor - Start the client http://localhost:4600:
pnpm ex:clientUsequarterback+ADMIN@atypon.comandasdfasdfto login as admin.quarterback+USER@atypon.comasdfasdfis the other user.
Also, if you were to remove a package inside packages the node_modules in the other packages that import it must be deleted (even after you do pnpm i). The symlinks are not always removed properly it seems. rm -rf node_modules sometimes help to other problems as well..
quarterback-packages includes the deployed packages that are used in Manuscripts app.
- If you didn't clone the submodules, install with
pnpm --filter \"./quarterback-packages/**\" iotherwise just usepnpm i - Copy the environment variables:
cp ./quarterback-packages/api/.example-env ./quarterback-packages/api/.env && cp ./quarterback-packages/db/.example-env ./quarterback-packages/db/.env - Migrate the database:
pnpm --filter @manuscripts/quarterback-db migrate - Bundle the libraries and start the Quarterback API at http://localhost:5500 with:
pnpm start
You should run commands to individual packages with eg: pnpm --filter @manuscripts/examples-track-api watch. To run them recursively for every package you can use -r eg: pnpm -r build.
admin
email: quarterback+ADMIN@atypon.com
pass: asdfasdf
user
email: quarterback+USER@atypon.com
pass: asdfasdf
You can add a submodule with eg: git submodule add -b quarterback-integration git@gitlab.com:mpapp-public/manuscripts-library.git examples-packages/library
After which you should also add the package to the source control: git add examples-packages/library
Any time you update a submodule and push to its quarterback-integration branch, you must then also execute git add examples-packages/<module> here to update the tracked commit.
Use this guide to publish new versions using Changesets and Github Actions