fedipage/README.md

License

This project (excluding post content itself) is released under the Apache License v2

Fresh install

Changing Default Sections

By default this site contains the following three blog sections: news, projects, and resource. Unfortunately the sections arent easily configurable just yet.

Renaming

1. Modify ./clean-build.cjs at the bottom of the file to include the name of the new section.
2. Change or create a new directory for section content under /content/<new_section>

Update /hugo.toml

You can use /hugo.toml.example as a starting point. Copy this file (dont move it) to /hugo.toml and then edit it.

This is the main configuration file. All of the setting in this file need to be set. There are other settings, the defaults, set in /config/hugo.toml, there is no need to touch this file, only the settings int he configuration at the root.

For some of the values in this file you can leave the defaults, but for most the values will need to be updated to match your site.

The file is commented to help understand the various variables.

Setup Firebase

First go to Firebase and sign up for an account here: https://console.firebase.google.com/

Then go to create new project, select a unique project name, follow the prompts and it will generate a project space for you. The only service you care about though is Firebase so from the dashboard select Firebase and then click the "create database" button. When prompted make sure you choose production server and not test. Withing a few minutes you should have a Firebase instance ready.

Next all that is left is to get your API access info which we will use later.

To start go to your project settings and under the General tab you should see a field labeled Project ID. Save this for later.

Next go to the Service Accounts tab and select Generate new private key. This will download a json file containing your keys. In the JSON open it up and find the value of the private_key field, and the client_email field These will be used later.

Firebase should now be ready to go! You can come back here to see the DB populate once the app starts running.

Setup Vercel

First go to the Vercel website and create a team to use when deploying if you'd like. This will be used in the next step during linking, be sure to use this team.

Then from the root of the project run the following:

vercel login
vercel link

When asked to "link to existing project" select no since this is your first time deploying.

This will then build and upload your project. It may take a few minutes. You may see the following error in the end Error: Failed to detect project settings. Please try again. If you see it but there are no other errors then it probably worked. Check your dashboard at Vercel.com and you should see an empty project was created.

After it is created you have to first make sure you updated /clean-build.cjs, if you changed the name or number of any of the sections. If not make that change now. Finally go to the settings for the newly created project and in the general section add the following as an "override" to the build command:

hugo --gc && node clean-build.cjs

This is a huge hack but the only solution I could find, if someone has a better way to do this please let me know or submit a PR.

Populate Vercel Env Variables

Next go to your Vercel dashboard then navigate to to your new project. In the settings tab there should be an Environment Variables section. Here is where we will populate those.

First generate your public and private keys used for ActivityPub. It is important you dont loose these as they identify your site. So save them.

npm install ts-node typescript '@types/node'
./node_modules/.bin/ts-node --esm generateKeys.mts

We will use these keys to set the values in the next step.

Now lets set the environment values to be used in Vercel (this mostly only effect the stuff under /api).

• POLL_MILLISECONDS: Set to 250000 or higher. This sets the minimum wait time between calls to the send-note endpoint. You may wish to adjust the cronjob in vercel.json as well.
• ACTIVITYPUB_PRIVATE_KEY: Get this value from generating the keys in the previous step. Note: When you paste in the key vercel will warn about newlines, you must ignore the warning.
• ACTIVITYPUB_PUBLIC_KEY: Get this value from generating the keys in the previous step. Note: When you paste in the key vercel will warn about newlines, you must ignore the warning.
• FIREBASE_PRIVATE_KEY: The value from earlier when setting up Firebase contained in the json. This is not the same as the ACTIVITYPUB_PRIVATE_KEY we generated a moment ago.
• FIREBASE_CLIENT_EMAIL: The value from earlier when setting up Firebase contained in the json
• NEXT_PUBLIC_FIREBASE_PROJECT_ID: The value shown in Firebase from the easlier step.
• ACTIVITYPUB_URL: This should be the same as the BaseURL setting for your sight. For example https://fedipage.com/. The trailing slash is very important dont forget it.
• ACTIVITYPUB_USER: The username of the ActivityPub user. This can have any capitalization you want and will be made lower when needed.
• ACTIVITYPUB_ALIAS: Optional if you dont want to set it. This should be a url to a fediverse account you want to designate as an alias. For example https://qoto.org/@fedipage
• ACTIVITYPUB_NAME: The full display name of the ActivityPub user. It can contain spacing and punctuation.
• ACTIVITYPUB_SUMMARY: The ActivityPub summary for the user. It appears right under their handle usually

Finally open the /vercel.json file and find the line that has /fedipage on it and change that to the name of your user ActivityPub username (apUser), but in all lowercase.

Configure domains

In the project settings go to the Domains section. Here you can add custom domains and it shows you how to configure them. These steps shouldnt effect the source code.

Setup Gitlab CI

First look at the content of the /.vercel/project.json file, this was created earlier from the vercel link command. This contains the org id and project id values. We will set these in GitLab's CI.

Go to your GitLab project and find the settings on CI/CD and under there you will find variables. Here we will add a few relevant variables.

• VERCEL_ORG_ID: Get this from /.vercel/project.json under orgId
• VERCEL_PROJECT_ID: Get this from /.vercel/project.json under projectId
• VERCEL_TOKEN: This can be generated under your vercel's account settings under the token submenu. Mask this and make it availible to only protected.
• VERCEL_SCOPE: Set to vercel team id you want to use, find with vercel team ls after the team is created, or if it already exists.

Customize your content

The content directory is currently empty to make it easier for projects to maintain updates. If you need an example of a working content directory see our live page's content here https://git.qoto.org/fedipage/fedipage/-/tree/master/content.

Make sure to do the following:

• Add a /content/_index.md, see the example above for the format of shortcodes for use in the index.
• Modify /layouts/partials/top_list_* to represent the section titles you want to use.
• Add a folder for each section you configured (by default news, projects, and resource) and fill it with content.

Microblog Side Menu

We also need to configure the sidebar's microblog to point to your alias account. If you dont have one you may want to disable this entirely.

It is pretty simpler first just go here and fill out the form: https://www.mastofeed.com/ . Feel free to set the UI scale to whatever you want but I find 80 works best. Also select the light theme to it matches. Make sure you uncheck show header as well. Finally set the width to a value of 100%.

Just copy and paste the iframe result into the /layouts/partials/microblog_iframe.html

Final steps

All that is left now is to push your code to your GitLab repo. At that point the .gitlab-ci.yaml file should automatically do the rest. After a few minutes you should have a running static site with full ActivityPub support. Enjoy.

Development

Please see the CONTRIBUTING.md file for instructions regarding development and contribution.