Skip to content

Latest commit

 

History

History
282 lines (206 loc) · 10.3 KB

SELF-HOSTING.md

File metadata and controls

282 lines (206 loc) · 10.3 KB
Raw

self-hosting

To self-host giscus, you need to create a new GitHub App and deploy the web app. You can use this guide as a reference.

create a new GitHub App

Register new GitHub App


  • image

    • Feel free to name it whatever you want (e.g. myblog-comments). I would appreciate it if you indicate that it is a self-hosted version of giscus (with the link) in the description.
    • Use https://giscus.app as the homepage URL unless you also accept any users to use your service on their repositories.

Identifying and authorizing users


  • image

    • Use https://[YOUR-DOMAIN-HERE]/api/oauth/authorized as the authorization callback URL, e.g. https://giscus.app/api/oauth/authorized.

    • Do not check "Expire user authorization tokens", as giscus currently does not support it.

      You can change TOKEN_VALIDITY_PERIOD in the code instead, which will automatically revoke user tokens and sign them out after that period.

    • Do not check "Request user authorization (OAuth) during installation".

Post installation


  • image

    • Not needed.

Webhook


  • image

    • Not needed. Uncheck "Active".

Repository permissions


  • image

    • Enable "Read & write" access for "Discussions". This is the only permission that you need, leave everything else as-is.

Organization permissions


  • image

    • Not needed.

User permissions


  • image

    • You don't need to change anything in this section. Leave "Where can this GitHub App be installed?" set to "Only on this account", unless you also accept any users to use your service on their repositories.

Create GitHub App


  • image

    • Click the button.

generate a private key


  • image

    • Upon registration, you will need to create a private key in order to install the app.


  • image

    • Click the button.


  • image

    • The private key will be downloaded to your device.

generate a client secret


  • image

    • Click the "Generate a new client secret" button.


  • image

    • Copy your client secret and store it somewhere safe.

copy App ID and Client ID


  • image

    • Copy the "App ID" and "Client ID" values and store them somewhere.

install the app


  • image

    • Click on the "Install App" sidebar menu and click on the "Install" button on your account.


  • image

    • Choose "Only select repositories" and select the repositories where giscus will be installed on.

      Alternatively, you can choose "All repositories". However, note that this will grant the app access to all of your repositories' discussions, including private ones. This also means that anyone can use the app to read and post any discussions in your repositories, as long as they know the repository names.


  • image

    • Click the button.

configure Supabase for caching access tokens (optional)

GitHub App installation access tokens have a 60 minute TTL. You can configure giscus to cache the tokens in a Supabase table. This reduces the number of token requests to GitHub, which helps prevent the app from hitting the rate limit.

  • Log in to Supabase.
  • Create a new project.
  • Create a new table within the project. The table name can be arbitrary, but giscus uses installation_access_tokens as the default.
  • Use the following schema for the table:
    image 
    installation_id: int8, no default value, primary key, uncheck Is Identity
token: varchar, no default value
expires_at: timestamptz, no default value
created_at: timestamptz, default value NOW()
updated_at: timestamptz, default value NOW()

None of the columns are nullable (uncheck Is Nullable via the gear icon).
Only installation_id is the primary key.
  • Take note of your Supabase project's URL (https://xxxxx.supabase.co) and your API key.
  • Make sure that you either:
    • Disable Row Level Security (RLS) on the table, or
    • Use the secret service_role API key.

deploy giscus

The giscus.app website is hosted on Vercel, but you can deploy it anywhere that can run a Next.js application and its serverless functions.

As a Next.js application with API routes

  • Clone the repository.

  • Generate a random string with a reasonable length (e.g. 64 characters) that will be used to encrypt the user token.

  • Set the following example environment variables in your deployment and change the values accordingly. On a server, you can put it in a .env.local file and Next.js will automatically pick it up.

    NEXT_PUBLIC_GISCUS_APP_HOST=https://giscus.app
GITHUB_APP_ID=123456
GITHUB_CLIENT_ID=Iv1.abcd1234wxyz5678
GITHUB_CLIENT_SECRET=abcd1234wxyz5678abcd1234wxyz5678abcd1234
GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nENTER-KEY-HERE-WITHOUT-LINE-BREAKS\n-----END RSA PRIVATE
KEY-----"
ENCRYPTION_PASSWORD=s0m3r4nd0mstr1ngw1thh1gh3ntr0py
SUPABASE_KEY=eyYlM4o.eyyH3Ll0oW0rLD
SUPABASE_URL=https://somerandomprojectname.supabase.co
SUPABASE_INSTALLATION_ACCESS_TOKENS_TABLE=installation_access_tokens
ORIGINS=["https://giscus.app", "https://giscus.vercel.app"]
ORIGINS_REGEX=["http://localhost:[0-9]+"]

  • Install the dependencies.

    yarn install

  • Build the application.

    yarn build

  • Start the server.

    yarn start

As a static website and separate serverless functions

If you wish to deploy the web app and the APIs (serverless functions) separately, you'll need to:

  • Take out and adapt the functions in the pages/api directory to your serverless platform.

  • If the web app and serverless functions are deployed on different domains, you'll need to change the service functions that calls the /api/* route to point to your serverless functions domain instead.

    Make sure that the CORS policy of the serverless functions allow requests from the web app.

  • Build the web app with yarn build, then export the static HTML version with yarn next export.

  • Serve the out directory, which contains the static website.

use the deployed self-hosted giscus

  • You can use the main page of the website to generate the client script configurations (e.g. data-repo-id, data-category-id) just like on giscus.app.
  • Include the script tag to your webpage, but replace https://giscus.app/client.js with https://[YOUR-DOMAIN-HERE]/client.js. You can also edit the Configuration component to do this automatically.

If you have any questions, ask them on the Q&A discussion. If you encounter any problems, create a new issue.