Skip to content

Latest commit

 

History

History
245 lines (175 loc) · 8.64 KB

SELF-HOSTING.md

File metadata and controls

245 lines (175 loc) · 8.64 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.

  • 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 example environment variables in your deployment and change the values accordingly. On a server, you can put them in a .env.local file and Next.js will automatically pick it up.

  • Install the dependencies.

    yarn install

  • Build the application.

    yarn build

  • Start the server.

    yarn start

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. Make sure you use the client script that is hosted from your deployment.

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