Skip to content

README.md

Latest commit

 

History

History
50 lines (31 loc) · 4.22 KB

README.md

File metadata and controls

50 lines (31 loc) · 4.22 KB
Raw

AVAnnotate Admin Client

This repository contains the code for the admin backend that powers AVAnnotate sites. It is made with the Astro framework, with a backend powered entirely by GitHub. It also uses React for client-side components.

Local Development

If you have access to the project on Netlify, install the Netlify CLI with npm install -g netlify-cli, then run netlify link in the project root to link your local repo to the desired Netlify project (for most local development this should probably be the staging instance). Once that link is done you can start a local server with netlify dev. In this case you don't need to worry about maintaining a local .env file for environment variables, since Netlify will inject them.

You can also run a local environment without linking to Netlify by running npm run dev. In this case you'll need a local .env file; copy the contents of .env.example and fill in the client ID and secret for the GitHub application you're using for authentication. (Values for these secrets can be copied from the Netlify projects, under Project Configuration -> Environment Variables.)

Note that running the site locally still requires authentication via GitHub, and changes made to projects will be applied, so be sure to create testing projects for playing around with any new and untested features.

UTexas GitHub Enterprise Managed User (EMU) login

A second "Sign in with UTexas EID" button can be shown on the sign-in page to let UTexas users authenticate via the GitHub Enterprise Managed Users SSO for the utexas-internal enterprise (https://github.com/enterprises/utexas-internal).

To enable this button you need a separate OAuth App registered inside the UTexas enterprise and two additional environment variables:

Variable Description
PUBLIC_UTEXAS_GITHUB_CLIENT_ID Client ID of the OAuth App created inside the UTexas enterprise
UTEXAS_GITHUB_CLIENT_SECRET Client secret for that OAuth App (server-side only)

Creating the OAuth App:

  1. Navigate to https://github.com/enterprises/utexas-internal (requires enterprise admin access).
  2. Go to Settings → OAuth Apps → New OAuth App. (this is actually under the developer section at the very bottom of your org's settings on the left.)
  3. Set Authorization callback URL to {PUBLIC_REDIRECT_URL}/git-enterprise (e.g. https://avannotate.netlify.app/git-enterprise).
  4. Copy the Client ID into PUBLIC_UTEXAS_GITHUB_CLIENT_ID and generate/copy a Client secret into UTEXAS_GITHUB_CLIENT_SECRET.

When PUBLIC_UTEXAS_GITHUB_CLIENT_ID is blank (the default), the UTexas EID button is hidden, so the sign-in page works exactly as before for non-UTexas deployments.

Creating projects as a UTexas EMU user

GitHub Enterprise Managed Users are isolated to their enterprise and cannot access GitHub repositories outside it — including the AVAnnotate project template (AVAnnotate/project-template). Without extra setup, UTexas users will see a "repo create failed" error when they try to create a new project.

To fix this, fork the template into the UTexas enterprise and tell AVAnnotate where to find it:

  1. Fork the template — inside the UTexas enterprise, fork or import AVAnnotate/project-template into a UTexas enterprise org (e.g. utexas-avannotate/project-template).
  2. Mark it as a template — in the forked repo's Settings → General, check "Template repository".
  3. Set the two new environment variables:
Variable Description
UTEXAS_GIT_REPO_ORG GitHub org (inside the enterprise) that owns the forked template, e.g. utexas-avannotate
UTEXAS_GIT_REPO_PROJECT_TEMPLATE Repo name of the fork; leave blank to use project-template

With these variables set, UTexas users' project creation calls will use the enterprise copy of the template instead of the one outside the enterprise.

Feel free to check our documentation or jump into our Discord server.