@toniq-labs/fleek-iterative-deploy

fleek-iterative-deploy

Package that will iteratively deploy a site to Fleek by gradually committing all changed files to the deploy directory in a dedicated deploy branch.

Requires Node.js 16.

Bonus points: you won't use up your Fleek computation minutes because GitHub (or whatever system you run this package with) will be running your build command!

What this solves

Fleek can only handle so many bytes per individual deploy, totally failing when that limit is reached. Typically this is issue is avoided by manually committing files gradually, which is a huge pain! This script does it automatically and seamlessly!

How this works

This package creates and manages a branch in your repo which Fleek should be configured to deploy from. This package iteratively adds files from your build to that branch and waits for the subsequently triggered Fleek deploy to finish, then adds more files.

Usage steps

Note that you will need to create a new Fleek site for this to work, as that is the only way to configure which branch Fleek deploys from (step 3 below).

1. Install to your repo

npm i -D @toniq-labs/fleek-iterative-deploy

2. Set environment variables

Use GitHub repo secrets to add env variables for GitHub Actions.

See the Obtaining Fleek keys section at the bottom of this README for helping getting the necessary keys.

1. Go to your repository
2. Click on Settings
3. Click on Secrets, then Actions
4. Click the New repository secret button
5. Use the key and values:
   • FLEEK_API_KEY: this should be an API key generated by Fleek.
   • FLEEK_TEAM_ID: this should be set to your Fleek team id.
   • FLEEK_SITE_ID: this should be the id (not name or IC dub domain) for your Fleek site.

3. Set your Fleek deploy branch to FLEEK_ITERATIVE_DEPLOY

1. Create, if it doesn't exist already, a branch in your repo named FLEEK_ITERATIVE_DEPLOY.
2. Create a new Fleek site.
3. Select your relevant repository.
4. Set the deploy branch for this new site to FLEEK_ITERATIVE_DEPLOY.

The FLEEK_ITERATIVE_DEPLOY branch will be managed by this package, you should not edit it. You can customize this branch name via the fleekDeployBranchName input, as explained in the later Custom inputs section.

4. Clear your build command from Fleek

Make sure that your Fleek deploy settings do not have a build command. npx @toniq-labs/fleek-iterative-deploy will run the build command for you.

5. Set your Fleek publicDir to build

Make sure your Fleek deploy settings include build as the "Publish directory" or publicDir. This package will add files to the build dir for Fleek to deploy.

The name of this directory can be customized via the fleekPublicDir input, as explained in the later Custom inputs section.

6. Set your build command to npm run build

This package will run npm run build to build the output which will get deployed to Fleek. This command can be customized via the buildCommand input, as explained in the later Custom inputs section.

7. Create a GitHub Actions workflow

Add a GitHub Actions workflow that triggers when you push to main (or master or whatever branch you wish). See an example here: https://github.com/toniq-labs/test-iterative-fleek-deploy/blob/main/.github/workflows/test-fleek-iterative-deploy.yml

As in the example, your workflow must at least do the following:

1. set env variables so that this package can access them (see the example file linked above on how to do that, it's the part under env:).
2. run npx @toniq-labs/fleek-iterative-deploy

In addition to those requirements, it's probably best to also include the following tips. All of these are included in the example file linked above.

1. Use concurrency with a static group and cancel-in-progress:

   concurrency:
      group: 'fleek-deploy'
      cancel-in-progress: true
   

2. Set fetch-depth: 0 in actions/checkout@v3:

   - uses: actions/checkout@v3
       with:
         fetch-depth: 0
   

8. Customize inputs

If needed, customize your inputs to npx @toniq-labs/fleek-iterative-deploy. See the Custom inputs section at the bottom of the page for defaults.

9. Push!

With everything setup in your GitHub action, simply push to your main branch and the GitHub Action should run and deploy everything automatically!

Extra package commands

Get Fleek Site ids

I haven't found a good way to find Fleek site ids, so here's how to get a list. It'll simply log the list of sites given your env Fleek API key and team id variables.

export FLEEK_API_KEY='insertYourKeyHere'; export FLEEK_TEAM_ID='insertYourTeamIdHere'; npx @toniq-labs/fleek-iterative-deploy --sites

Dry run

This allows you to test inputs. All inputs will be set and logged but the iterative deploy won't run.

npx @toniq-labs/fleek-iterative-deploy --dry-run

Custom inputs

npx @toniq-labs/fleek-iterative-deploy "<buildCommand>" "<fleekPublicDir>" "<fleekDeployBranchName>"

• buildCommand: this is the bash command which @toniq-labs/fleek-iterative-deploy will run to build your website.
• fleekPublicDir: this is the directory which Fleek is configured to deploy files from; this should match the publicDir property in a Fleek config file.
• fleekDeployBranchName: this is the branch which Fleek will deploy from. This should not be the same as the branch that triggers your GitHub Action (which will probably be main or master).

The defaults are listed in the following object:

import {DeployIterativelyInputs} from './iterative-deploy';

export const defaultInputs: Readonly<DeployIterativelyInputs> = {
    buildCommand: 'npm run build',
    fleekPublicDir: 'build',
    fleekDeployBranchName: 'FLEEK_ITERATIVE_DEPLOY',
} as const;

Skipping deploy

To skip a deploy, add nobuild! or !nobuild to your latest commit message before pushing to your branch. This will abort the deploy before it starts.

Forcing a deploy

To force a deploy, add forcefleekdeploy! or !forcefleekdeploy to your latest commit message before pushing. This will skip checking if any changes have been made since the last deploy, and just try to deploy everything.

Obtaining Fleek keys

Fleek api key: FLEEK_API_KEY

Your Fleek API key must be stored in the FLEEK_API_KEY env variable before running commands from this package. To get your Fleek API key, do the following:

1. Go to the Fleek app
2. Login
3. Click on your user name in the ver bottom left corner
4. Click Settings
5. Click Generate API under the Hosting API section.
6. Copy that value and save it into the env variable FLEEK_API_KEY before running any commands from this package.

Fleek team id: FLEEK_TEAM_ID

Your team id must be saved into the FLEEK_TEAM_ID env variable. To find this do the following:

1. Go to the Fleek app
2. Login
3. Look at the URL
4. Copy the id that's after accountID= in the URL.
5. Save this into the FLEEK_TEAM_ID env variable before running commands from this package.

Fleek site id: FLEEK_SITE_ID

The id of the Fleek site you want to operate on must be set in the FLEEK_SITE_ID env variable. Finding your site's id is a little trickier, in my experience. Luckily, if you have the previous two env variables set already, you can use this package to find your site ids! To find your side id, do the following:

1. Make sure you've retrieved the previous two env variables for your team id and API key.
2. run export FLEEK_API_KEY='insertYourKeyHere'; export FLEEK_TEAM_ID='insertYourTeamIdHere'; npx @toniq-labs/fleek-iterative-deploy --sites
3. Inspect the stdout output of the command. Find the site with the name you want, then copy its id.
4. Save this id into the FLEEK_SITE_ID env variable before running the full iterative deploy command from this package.

Example

The following repos currently use this package to deploy to the IC via Fleek.

• https://github.com/toniq-labs/test-iterative-fleek-deploy
• https://github.com/Toniq-Labs/entrepot-app