Project Setup - zyplos/bluesky-handles-kiosk GitHub Wiki

If you'd like to set this project up for your own domains, you'll first need a PostgreSQL server set up, secured, and ready to take remote connections. This guide will not cover how to set up a PostgreSQL server. The rest of the things we'll need, we'll go through step by step.

[!IMPORTANT] Part of this guide will be changing your domain's nameservers to Vercel's nameservers. This allows Vercel to capture all subdomain traffic on your domain, letting this project respond to Bluesky's request to verify that a handle actually belongs to a domain its under.

You can recreate your domain's DNS records in Vercel's DNS Records editor, but if this is a dealbreaker, you can deploy this project on your own infrastructure. Just make sure your nginx or Apache config is set up so that this project can capture subdomain requests and can respond to things needed by ./middleware.ts.

This guide will go through the following things that are required:

• Creating an application in the Discord Developer Portal
• Deploying this project to Vercel
• Adding domains to Vercel
• Configuring this project to work with your domains
• Enabling analytics
• Customizing the theme and landing page

Creating an application in the Discord Developer Portal

You'll need to create an application in the Discord Developer Portal so we can let users use their Discord accounts to sign in. Visit https://discord.com/developers/applications and click "New Application" at the top right. Give it a name (keeping in mind that users logging in will see it) and assign it under a team if you're in an organization. Once created, you'll be taken to a new screen where you can give your application an icon if you'd like (which users will also see). There is a premade ./icon.png image if you'd like to use that.

Click OAuth on the sidebar. Note down the Client ID somewhere. Under Client Secret, click "Reset Secret" to generate a new client secret. Note it down, you won't be able to see it again!

Scroll down to the Redirects section. Click "Add Redirect" and enter https://<the domain you're deploying>/api/auth/callback/discord in the textbox that appears. (if you'd like to run this project locally, add http://localhost:3000/api/auth/callback/discord to the list as well). Click the "Save Changes" button toward the bottom right. You should see something like this:

[!NOTE] You don't have to use Discord for user sign ins. This project uses Auth.js, letting you use Google, GitHub, and many more OAuth providers. You can also restrict user sign ins to just people in your organization. Refer to the OAuth Providers and Restricting user access to the app pages on the Auth.js site if you'd like to learn more. You can find this project's Auth.js config in ./internals/auth.ts.

Deploying this project to Vercel

For easy setup, this project was made to be deployed on Vercel. You can quickly clone this repo and deploy it on Vercel by visiting this link: https://vercel.com/new/clone?repository-url=https://github.com/zyplos/bluesky-handles-kiosk

You'll be asked to create a new git repository for your deployment. This will be useful if you'd like to customize the look of this project later. Give your new repo a descriptive name and choose a Vercel Team to deploy the project under. Click "Create" and you should see Vercel start to build and deploy the project. Once Vercel's done, you should see a preview of the site. It should show "not configured!" as we haven't configured the project yet. Before we do, we'll need to add the custom domains we want to our Vercel project.

Adding domains to Vercel

If you're still on the previous page, click "Add Domain" to be taken to the domains your Vercel deployment is associated with. Otherwise, find the project you just deployed by going to your team's dashboard. Click on it and click "Settings" at the end of the top navbar tabs. Click "Domains" on the left sidebar. You should see something like this:

Click the "Add Domain" button on the right. Leave "Connect to an environment: Production" as is. You'll need to add 2 domains:

• <the domain you're using> (i.e. example.com)
• *.<your domain> (i.e. *.example.com)

You should see something like this:

As mentioned at the beginning of the guide, you will need to use Vercel's nameservers for the domain you're setting up for this project. This lets this project respond to Bluesky's requests to verify that a handle is under a domain. If you've set up any custom DNS records in your domain's registrar (MX records, CNAMEs, custom Minecraft ips, etc.) take note of them so you can recreate them in Vercel's DNS Records editor (found in the "Domains" tab on your team's dashboard home).

Follow your domain registrar's guide to changing your domain's nameservers (for example, here is Namecheap's guide). Change them to the ones Vercel shows you in your Domain settings page. It may take a few minutes or a few hours for Vercel to verify the changes. A successfully set up domain should look something like this, with blue checkmarks to signify that Vercel has verified your domain is using their nameservers:

You can add more domains if you'd like, just remember you need to add two entries (the domain and the subdomain wildcard) along with changing the domain to use Vercel nameservers.

Configuring this project to work with your domains

This section will go through configuring this project to use your PostgreSQL database and Discord OAuth application. In your Vercel project's Settings page, click "Environment Variables" on the left sidebar.

You will need to look at this project's .env.example file to see what keys and values you need to put into Vercel's "Environment Variables" page. Click the "Add Another" button below the row of textboxes to add all the required keys.

You should see something like this with the exact keys, but different values based on your own PostgreSQL server and Discord application credentials:

[!NOTE] Vercel adds a little gray tab in spaces to make it obvious that the value contains a space. If you're adding multiple domains in the HOSTNAMES key, make sure each domain is separated by a space and not an underscore.

Click "Save". You should see your keys get saved and your values get redacted. Click the eye icon to reveal the values. Make sure they're correct!

You now need to redeploy the project for changes to take effect. At the bottom left, you might see a prompt asking you to redeploy your project.

If you don't see this prompt or you clicked off the page, you can redeploy from the "Deployments" tab at the top navbar. Click the three dots next to your "Current" production deployment and click "Redeploy."

[!WARNING] Make sure you are redeploying to a "Production" deployment. Preview deployments won't deploy the project to the domain you've set up (unless you've configured it to do so).

You'll see a prompt asking you to redeploy. Vercel will tell you what domains it is about to redeploy to. Check that everything's in order. If everything seems fine, click "Redeploy."

Once the new deployment is done, visit the domain you've set up. You should see a landing page like the following:

Users should be able to sign in now and claim handles. Should any errors arise, check that:

• you've configured your PostgreSQL server to correctly respond to remote connections
• the credentials for your PostgreSQL server and Discord application are set correctly in your Environment Variables
• you've correctly setup domains in your project settings

You can check the "Logs" tab at the top and monitor for any errors to help debug any problems. If you change your environment variables, remember to redeploy for your changes to take effect.

Enabling analytics

This project comes with Vercel Analytics if you'd like to monitor usage of your site. It is disabled by default. If you'd like to enable it, go to the "Analytics" tab at the top navbar.

Customizing the theme and landing page

If you'd like to customize how the site looks, go to the Customization page for instructions on how to do this.