Skip to content
This repository has been archived by the owner on Jul 21, 2023. It is now read-only.

Latest commit

 

History

History
184 lines (139 loc) · 11.9 KB

README.md

File metadata and controls

184 lines (139 loc) · 11.9 KB
Raw

Midspace virtual conference platform

Note: the official Midspace instance at midspace.app is no longer available. You can still host your own Midspace instance using the open-source code. Thanks for using Midspace!

This is version 3 of Midspace - more functional, more robust, more scalable, and 100% open source!

If you want to contribute to Midspace, please read our contribution guidelines.

Structure

Folder Contents ReadMe
aws Infrastructure as code for AWS AWS Readme
frontend The frontend React web app Frontend Readme
hasura The Hasura GraphQL configuration, actions and seed data. Hasura Readme
services Micro-services
services/actions A service that handles most Hasura actions. Actions service readme
services/auth Auth service readme
services/caches Caches service readme
services/realtime A service that handles realtime interactions like chat and presence. Realtime service readme
services/playout A service that controls video broadcast pipelines. Playout service readme

Quick Setup vs. Full Setup vs. Production

For contributors that only want to play with the user interface, the "Quick" version of the following instructions should get you a minimal working setup. Just skip over the steps marked Full Setup or Production and follow the steps marked Quick Setup.

Warning: The Quick Setup instructions are still being debugged and may or may not work yet!!

Caveat: The word "Quick" should be taken with a grain of salt. Even this streamlined path is likely to take you a day or two.

To test changes that affect other parts of the platform, skip the steps marked Quick Setup and follow steps marked Full Setup. To deploy Midspace publicly or run your own conference on Midspace, follow the steps marked Production as well.

Local Software Installation

  1. VSCode
    • We also recommend you install the "recommended extensions" listed in the .vscode/extensions folder. VSCode may offer to install them automatically.
    • If using Windows:
      1. Note that you may encounter issues setting up a development environment that are specific to Windows, in which case README pull requests are welcome!
      2. Install Git command line if you haven't already.
      3. Open or restart VSCode, and open a terminal with menu Terminal -> New Terminal
      4. Next to the big + sign in the right side of the terminal header, there's a dropdown with tooltip "Launch Profile...". Click it and select Git Bash.
  2. Node.js 17
  3. pnpm 16.30 or later
  4. Docker Desktop - Midspace uses Docker Compose, now included in the Docker CLI.
  5. Hasura CLI
  6. Full Setup: AWS CLI and awsvault
  7. Production: Heroku CLI if you will be deploying Midspace publicly.

Generate Hasura Admin Secret

The Hasura GraphQL engine will be configured with an arbitrary admin secret value, and this value is needed for configuring several other services that make up Midspace, so generate a secure secret value now and make note of it. A suggested method is a hex string representing a 128-bit value, which can be generated using one of the methods below depending on which tools are available on your system.

  • openssl rand -hex 16
  • node -e "console.log(require('crypto').randomBytes(16).toString('hex'))"

Several other setup steps require an arbitrarily selected secret value shared between services, and this method may be used for generating those values as well.

Install Packages

Install all node packages (pnpm descends into subdirectories and creates all necessary node_modules directories):

pnpm i

Cloud Services

Midspace relies on various cloud services, which will need to be configured for local development as well.

  1. Full Setup but not Production: Set up tunnels for enabling callbacks to services running locally
  2. Set up user authentication
  3. Full Setup: Set up AWS account and Deploy AWS CloudFormation Stacks
  4. Set up video chat service
  5. Full Setup: Create a SendGrid account and an API key for it.
    1. Take note of the API key when creating the account; you will not be able to view it later without updating it to a new value.
    2. Also set up Signed Event Webhook Requests and generate a verification key pair. You will need the public key, but you can come back to the Sendgrid mail settings page → Signed Event Webhook Requests modal to view it later.

Setting Up Local Working Copy

  1. Follow the Hasura setup: Midspace Hasura ReadMe
  2. Follow the Actions Service setup: Midspace Actions Service ReadMe
  3. Follow the Auth Service setup: Midspace Auth Service ReadMe
  4. Follow the Caches Service setup: Midspace Caches Service ReadMe
  5. Follow the Playout Service setup: Midspace Playout Service ReadMe
  6. Follow the Realtime Service setup: Midspace Realtime Service ReadMe
  7. Follow the Frontend setup: Midspace Frontend ReadMe
  8. Generate all GraphQL client code
    1. cd packages/shared/graphql
    2. cp .env.example .env
    3. Set environment variable values in .env as per other parts of Midspace, likely just HASURA_ADMIN_SECRET.
    4. Run the VSCode task All -- GraphQL Codegen. If there are errors, check that .env files have been populated in all relevant subdirectories as described in previous steps.
    5. Fixup currently required after running GraphQL Codegen: Some changes are made to the file frontend/src/generate/graphql.tsx that need to be undone:
      1. Restore this line at the beginning of the file: import { useQuery } from "@midspace/urql-hasura-cache-generic-resolver/useQuery";
      2. Revert all instances of Urql.useQuery< back to useQuery<.

Starting your local working copy

Once you have finished setup, it's easy to run the entire environment with a single VSCode task: "Run All -- Local Development". This task starts PacketRiot tunnels as well as all Midspace services.

Final Steps

  1. Once the system is up and running, open the app in your browser, log in, then navigate to https://<your-domain>/su and follow the instructions to set up a superuser.
    • In a production environment, we recommend using separate infrequently-accessed accounts for superusers, to reduce the risk and impact of security breaches.
    • In a production environment, we recommend using separate accounts for the various privileges available to superusers. For example, keep accounts with the ability to create conference codes separate from those able to modify the set of superusers.
  2. If running this software in a production environment, you will need to use the superuser configuration pages to initialise the System Configuration.
    • Fill out values for all available keys.
    • Refer to the description field of each key (in system.ConfigurationKey) for expected values.

If you alter environment config, Docker Compose config, etc., then all tasks must be restarted. Tasks can be killed in VSCode using Ctrl+C or by closing the terminal window they are running in. To kill Docker containers, you will need to manually terminate the container (e.g. by pressing the stop button in Docker Desktop)

Create a conference

When you log into Clowdr for the first time, there will be no conferences listed. You will need a demo code to create a conference, and this cannot yet be done through the Clowdr UI. To create a demo code:

  1. Go to the Data tab in the Hasura console.
  2. Open the conference > DemoCode table.
  3. Open the Insert Row tab. Ensure that id is set to Default and click Save. There is no need to enter any values manually.
  4. A code has now been created. Open the Browse Rows tab and find the new row in the table.
  5. Copy the id column of the new row. This is your demo code - you can use it to create a conference in the Midspace UI.

Modifying the default security settings

By default, only the creator of a conference has permission to view its elements. You can give permissions to other groups of users by opening the Content admin panel in Midspace. Click the yellow button with a lock icon to open the (conference-)global element security settings.

You probably want to at least add an entry for 'Organiser' permissions with the 'Organisers' group.

Formatting

This repository uses Prettier for auto-formatting and checks for both pushes and PRs. You may need to configure your editor to use Prettier (for example, by using the VSCode extension)

Notes

  • The various Procfiles are used by Heroku to determine what services to run.
  • In production deployments, you will want to regularly clear out old Hasura event logs or you will encounter performance issues. There is a stored procedure public.truncate_hasura_logs to clear out logs older than a week. You could, for example, deploy a Cron To Go task in Heroku that calls psql $DATABASE_URL -c "CALL public.truncate_hasura_logs()".

GitHub Actions Configuration (/Secrets)

If you want to configure the GitHub actions for CI, you will need to set the following secrets:

Secret Value
HASURA_ADMIN_SECRET The value of Hasura Cloud
HASURA_ENDPOINT The GraphQL API URL from Hasura Cloud but without the /v1/graphql path.
ACTION_BASE_URL As-per the Hasura Cloud environment variable.
REALTIME_BASE_URL As-per the Hasura Cloud environment variable.
HASURA_PERSONAL_ACCESS_TOKEN The value from Hasura Cloud
HASURA_PROJECT_ID The value from Hasura Cloud

Note:: The HASURA_ENDPOINT changes when if rename your project inside Hasura Cloud.