COSCRAD is a loose collaboration of several organizations, technical teams, and communities working in the space of custom software development for indigenous language revitalization and cultural research.
We have adopted the monorepo approach to allow our members to maximize opportunities for code sharing and collaboration, while maintaining autonomy and focus on their own individual projects within this workspace.
Our apps are of two kinds:
core coscrad applications
api(core back-end for the COSCRADweb of knowledge)coscrad-frontend(standard front-end for the COSCRADweb of knowledge)
community projects
tng-dictionary(maintained by Justin Bambrick, TNG)tsilqotin-language-hub(maintained by Justin Bambrick, TNG)tng-radio-hub(maintained by Blake Sellars, TNG)
The core apps are developed and maintained by the core COSCRAD team. These projects are subject to strict guidelines for code quality and automated test coverage.
The community projects currently consist of several prototypes of front-end clients that leverage the COSCRAD API. The Many ideas explored in the community projects will eventually find their way into Coscrad's core.
COSCRAD CLI
The coscrad-cli is a command line tool for data administration tasks. Its use is documented here
In the future, once our domain has been moved to a separate lib, we will move
the COSCRAD CLI to a standalone app in the mono-repo.
We maintain several libraries, which allow us to share code between applications in the monorepo. For example, we share validation constraints between the back-end and client to allow for a single, consistent implementation of validation logic.
We also share UX widgets
between prototype projects and coscrad-frontend. This provides a natural approach
to selectively incorporating new tools and features from these prototype projects.
@coscrad/api-interfaces@coscrad/data-types@coscrad/validation-constraints@coscrad/commands@coscrad/media-player
This monorepo workspace is managed using Nx. See the README in an individual app or lib to learn more about the tools used on that particular project.
You'll need Node v18.12.0. It is recommended that you install node using nvm).
You'll also need an instance of ArangoDB.
We recommend that you use yarn as a package manager, as it provides better support
for managing peer dependencies.
We provide an optional shell script for spinning up an ArangoDB instance. This will only work if you have docker installed on your development machine. Alternatively, you could run an ArangoDB instance on a VirtualBox VM, a local physical machine, in the cloud, or via one of Arango's enterprise hosting solutions.
Some functionality related to media management depends upon fluent-ffmpeg, which in turn requires ffmpeg to be installed on your OS.
For Ubuntu 20.04, you can run
sudo apt update
sudo apt install ffmpeg
to install ffmpeg.
Clone this repo
git clone https://github.com/COSCRAD/coscrad.git
cd into the repo's directory
cd coscrad
Install the dependencies
yarn install --frozen-lockfile
For convenience we have included a quality check script. This script will run lint, Jest tests and build for the front-end (coscrad-frontend) and back-end (api), and run the e2e tests via Cypress for the entire COSCRAD core.
npm run quality-check:coscrad
Contributors should ensure all of these quality checks pass on their end prior to submitting a PR. Note that eventually this will become the responsibility of our CI system and PRs that break the quality checks will automatically be rejected.
See the README in individual projects and libs for more details about how to run tests and static analsysis.
To build both the Coscrad front-end and back-end, run
npm run build:coscrad:prod
A project's build will appear in /dist/<project-name>. E.g., the build for the
backend, whose project is called api will appear in /dist/api
Note that when deploying the backend build, you can either set the environment
variables specified in sample.env to their production values by setting these
environment variables on your production server or by including a production.env
with the appropraite values at dist/apps/api/production.env (alongside main.js).
pm2 is a useful process manager for node applications. You may want to use NGinx as a reverse proxy and to manage your certificates using certbot.
We use Jenkins for continuous integration and continuous delivery. We have
integrated Jenkins with our GitHub repo via GitHub apps and GitHub hooks. We
currently use DigitalOcean cloud agents for our builds. We provide a Jenkinsfile
that specifies our pipeline as code. While this is reusable in principle, there is
a lot of magic required to configure the tooling in the background. Your best bet
is to contact us if you'd like to automate deployments of your own COSCRAD instance
to your own infra.