Self hosting instructions

[abersheeran]

Hello, I have a question to ask. Your server is blocked in my area, how can I copy your program to my own server?

[jdanyow]

There are two components- the utterances API (a node app) and the web site (static html/css/js site). I run the API on Azure and the web site on github pages.

To setup the API:

1. Create a new Azure Web App: https://portal.azure.com/#create/Microsoft.WebSite The free tier will work. A paid tier will work better. OS doesn't matter- windows or linux. Under "deployment options", choose "local git". Go back to the "general" tab and make note of the "git clone url" (eg https://[username]@[app name].scm.azurewebsites.net:443/[app name].git) and the "url" (eg https://[app name].azurewebsites.net).

2. Create a new github app: https://github.com/settings/apps/new Here are the fields that matter:

   field	value
   GitHub App name	your blog's name
   Description	your blog's description
   Homepage URL	your blog's url
   User authorization callback URL	the url of your azure web app, with /authorized appended. For example, https://my-awesome-blog.azurewebsites.net/authorized
   Webhook URL	It's a required field, but utterances doesn't use it. Pick anything... your blogs url... doesn't matter.
   Permissions	Issues: Read & Write. No other permissions necessary.
   Where can this GitHub App be installed	Only on this account

   Once you've created your app you'll be prompted to generate a private key. This is a required step. Utterances doesn't use the key so don't worry about remembering the value. Make note of your github apps Client ID and Client Secret... you'll need those values later...

3. Go back to your azure web app and navigate to the "application settings" tab, then scroll to the "application settings" area and add the following settings:

   setting	value
   BOT_TOKEN	a personal access token with public_repo scope that will be used when creating GitHub issues: generate here.
   CLIENT_ID	The client id to be used in the GitHub OAuth web application flow. Copy from your GitHub App's page.
   CLIENT_SECRET	The client secret for the OAuth web application flow. Copy from your GitHub App's page.
   STATE_PASSWORD	32 character password for encrypting state in request headers/cookies. Generate here.
   ORIGINS	comma delimited list of permitted origins. For CORS. Enter https://[your github account].github.io,http://localhost:4000)
   APP_ROOT	Your azure web app's url (eg https://my-awesome-blog.azurewebsites.net)
   USER_AGENT	The GitHub API requires a User-Agent header. Put anything here... "my awesome blog"... whatever.

4. Deploy the app...

   git clone https://github.com/utterance/utterances-oauth
   cd utterances-oauth
   git remote add azure [the azure web app's git clone url from step 1]
   git push azure

5. Verify the app is running by going to https://[app name].azurewebsites.net... you should see blank page with the text "alive".

To setup the web site:

1. Install yarn
2. Fork this repo: https://github.com/utterance/utterances
3. Clone your fork: git clone https://github.com/[your-acount]/utterances
4. Remove the && echo 'utteranc.es' > dist/CNAME from this line: https://github.com/utterance/utterances/blob/a8707dbc882410e40c4a98150577774891cd3f5b/package.json#L26 (this tells github pages what my custom domain name is... you won't need this)
5. Change this url to the url of your azure web app: https://github.com/utterance/utterances/blob/a8707dbc882410e40c4a98150577774891cd3f5b/src/utterances-api.ts#L2
6. Update some of the attributes here: https://github.com/utterance/utterances/blob/3d69c8b214fab101a6657909a0f4d5d45faeda06/src/index.html#L53-L68 Change src="https://utteranc.es/client.js" to https://[your github account].github.io/utterances/client.js Change repo="..." to whatever repo you're storing your blog comments in.
7. Execute yarn start, then go to http://localhost:4000/index.html and verify you're able to sign-in, post comments, etc.
8. Execute yarn run deploy to deploy to github pages. Then go to https://[your github account].github.io/utterances/... verify you can sign-in, post comments, etc.

Let me know if you have any questions :crystal_ball:

[abersheeran]

Thank your help. 😄 I will do it.

[arranf]

@jdanyow Would self hosting allow this to work with private repos?

[zchef2k]

@jdanyow Would self hosting allow this to work with private repos?

+1 on using private repos.

[jdanyow]

Self hosting will not enable commenting on private repos. Comments are made using the commenting user's github account. If the repo is private users won't be able to create issue comments in the repo unless you had previously given them access to the repo.

[Graborg]

Any reason the client code is implemented as an iframe?

[jdanyow]

@Graborg isolation

[psi-4ward]

So utterances-oauth is implemented as cloudflare-worker. To have a self-hosted solution it would be very nice to have a standalone server instance. Can we wrap it to run as ordinary node app?

[Graborg]

We did a fork of utterances and rebuilt the oauth in node. https://github.com/sebgroup/yttringar-oauth

It's built for another usecase, but most of the logic is the same. Note that '/token' route is now a GET request instead of POST.

Good luck.

[junaid33]

Trying to self-host utterances-oAuth with Azure is not working. It seems you're using Cloudflare Workers now. Can you provide instructions on how to self-host it there?