Skip to content

Home

Jump to bottom
Якоб Александрович edited this page Oct 10, 2022 · 6 revisions

Setting up the site 'Open Component Ecosystem'

General

Before you start, you need to have a Github token ready, and you need to setup your Supabase.

  1. Create your Github token.
    To get lists of apps and components from GitHub, using GraphQL queries, we need access to Github

    1. Login to github, then go to https://github.com/settings/tokens/new
    2. In Note, give your token a meaningful name, like 'OCE website access', so you can find it back later.
    3. Set the lifetime to no expiration
    4. Do not select any scopes.
    5. Click on Generate token, and copy the generated token somewhere in a text editor.

  2. Setup your Supabase database

    1. Login on Supabase (with your github account)
    2. Click on New project
    3. Give the project a meaningful name, like 'opencomponents'
    4. Create a nice and long strong password. Copy this password somewhere in a text editor.
      In this case, be advised to not use special characters, as they interfere with our URI
    5. Hit Create new project
      Wait till the database and API endpoints have been provisioned
    6. Go to Settings (the cog) and click on Database. Scroll down till you see Connection string
      Let's call this the 'simple connection string'
    7. Click on URI, then copy this somewhere in a text editor
    8. Replace [YOUR-PASSWORD] with the password that you created earlier
    9. Scroll down to Connection Pooling
    10. Set Pool mode to Session
    11. Copy the Connection string somewhere in a text editor

Local setup

After you've done your preparations, let's setup our local environment'

  1. Clone the project
    git clone [email protected]:bible-technology/opencomponents.io.git

  2. Run package installation
    cd opencomponents.io && yarn

  3. Make a copy of .env.local.example and rename it to .env.local
    cp .env.local.example .env.local

  4. Specify environment variables
    In the .env.local file, replace the dummy environment variables GITHUB_TOKEN and DATABASE_URL with the ones that you just created

  5. We use Prisma as the ORM for the database Nothing to be done here. We might want to remove this item

  6. As a database, we use a cloud instance of PostgreSQL (Supabase)
    For local development, you can use the local or the cloud version of Supabase.

    If you decide to run a local version of Supabase, your DATABASE_URL will look something like this:
    DATABASE_URL=postgresql://postgres:postgres@localhost:54322/postgres

  7. In order to populate the database with the needed tables, run yarn seed

  8. To verify that everything was setup correctly, run the command npx dotenv -e .env.local -- npx prisma studio in the console

  9. The Prisma web interface should start. If there are any errors, try running npx prisma generate

  10. You can now run yarn dev and navigate to http://localhost:3000. The apps and components repositories should be loaded.
    On the main page, the block with components and apps will be empty, since the data is taken from the database there.

  11. The database is populated when the hook in the GitHub repository is triggered. To configure locally, do the following:

  12. Launch the site if it is not already running: yarn dev

  13. Configure Ngrok and run on 3000 port

    ngrok http 3000

    You will see something like this

    Web Interface http://127.0.0.1:4040
Forwarding https://9a0b-43-1-42-21.eu.ngrok.io -> http://localhost:3000

    This is how we set up the tunnel, and all requests to https://[URL-ID].eu.ngrok.io will be redirected to our site http://localhost:3000

    In Web Interface we can see all incoming requests and responses from our API

  14. Now configure our repository

Serverless setup

  1. To deploy the project, use Netlify

    1. Login to Netlify
    2. Click on Add new site, then click on Import an existing project
    3. Connect to Github, then pick the correct repository and branch (probably main)
    4. Build command should be yarn build, Publish directory should be .next
    5. Click on Deploy site
      Probably this deploy will fail due to missing variables

  2. Setup correct deployment parameters

    1. Click on Site settings of the just created site
    2. Click on Build & deploy
    3. The Build image should be 'Ubuntu Focal 20.04'. If not, change it accordingly.
    4. In Enviroment variables, you need to create the following environment variables
      • DATABASE_URL: the Supabase 'simple connection string' (not the Connection Pooling one)
      • GITHUB_TOKEN: the token that you created earlier
      • NODE_VERSION: 16

  3. Go to Deploys, then click on Trigger deploy, then Clear cache and deploy site

    Important Note: During the initial build, prisma should populate the database. In case you run into errors because it didn't, follow the procedure under Database migrations

  4. After the initial build is successful, we need to replace DATABASE_URL with the Connection pooling link.
    Just replace the variable in DATABASE_URL with the Supabase Connection Pooling connection string

  5. Finish by triggering a new deploy.

Database migrations

In case there have been changes to the database structure (through the file schema.prisma), make the following temporary changes:

  • Go to Site Settings, Build & deploy
  • Click on Edit settings, under Build settings
  • Change the Build command to npx prisma generate && yarn build
  • Click on Save
  • Click on Edit variables, under Environment variables
  • Change the Database URL to the 'simple connection string'
  • Click on Save

After you have successfully re-deployed the site, you need to revert these changes.

More about Prism and Supabase

How to add a component or app

Basic setup

  1. In order for your app or component to be displayed in the list, just add the topic scripture-open-components for a component or scripture-open-apps for an app

Advanced setup

If you want the component to display dependencies, then you need to correctly configure the repository

  1. Create file oce.json

    {
  "name": "npm/@texttree/projector-mode-rcl",
  "version": "0.5.3",
  "date": "2022-04-14",
  "logo": "https://raw.githubusercontent.com/texttree/projector-mode-rcl/master/images/logo.png",
  "dependencies":["npm/core-js", "npm/@texttree/filter-translation-words-rcl"]
}

    name is the name of the package. For apps is not filled. This name will be used for binding through dependencies.

    Since the name may coincide in different languages, we use the prefix

    js - npm/

    php - composer/

    ruby - gem/

    python - pip/

    version - the latest version of the component or app

    date - date when the app or component was published (YYYY-MM-DD)

    logo - link to app logo. If not specified, it will be taken from https://raw.githubusercontent.com/[repo]/master/images/logo.jpg

    dependencies - is an array of dependencies. Here we specify the names of the packages with a prefix.

  2. Add a webhook so that when changes are made in the oce.json file or in the description, adding topics, etc. - these changes were recorded in the database

    Go to Settings -> WebHooks -> Add Webhook

    Payload URL - https://oce-site.netlify.app/api/webhook for production, https://[URL-ID].eu.ngrok.io/api/webhook for local work

    Content type - application/json

    Which events would you like to trigger this webhook? - Let me select individual events.

    Checking Pushes and Repositories

    Adding a webhook

  3. At this moment, a ping request will pass, and the data on the repository, as well as the data from the oce.json file, will be written to the database

Clone this wiki locally