Learn how to set up, configure and run your own Wuffle board.
Table of Contents |
---|
Install and Run |
Configure the GitHub App |
Connect GitHub Repositories |
Configure the Board |
Run in Production |
Run via Docker |
If you accounter problems during the setup, please file a help request.
Start from an empty folder:
# initialize a new app
npm init
# if you plan to check-in your board app,
# do not check-in node_modules
echo "node_modules" >> .gitignore
# do not check-in environment file, too
echo ".env" >> .gitignore
Install wuffle via npm
:
npm install wuffle
Starting the board by using the wuffle
executable:
npx wuffle
Open the app on localhost:3000
.
The first time setup guides you through the installation process and helps you to create a GitHub app. It also creates several assets in your local working directory: The .env
file contains all environment variables required to run the app. The wuffle.config.js
contains the board configuration.
Once re-started and properly configured, connect your GitHub repositories. Periodic background sync will pickup repositories, fetch issues from GitHub, and populate your board.
As a post-installation activity configure the user login flow. That allows users to log in to your board via GitHub to see their private repositories.
When going into production, run wuffle
with strict validation and production tweaks turned on:
NODE_ENV=production npx wuffle
The board connects to GitHub as a GitHub app. As part of the first-time setup, you create that GitHub app or import it into your environment.
You can setup the app manually, too.
The board requires your visitors to login via GitHub if they want to perform board operations or move cards around.
To enable the login flow, configure the User authorization callback URL
in your GitHub App settings page to point to $BASE_URL/wuffle/login/callback
.
Create your GitHub app and configure it according to the provided app mainfest.
In your current working directory, create a .env
file-based on our example. Fill in the configuration provided to you by GitHub.
Go to https://github.com/apps/{APP_NAME}/installations/new
to install the app for all desired repositories and organizations. That sets up the required change notifications and write permissions to keep the board in sync with GitHub issues.
The board is configured via a local wuffle.config.js
file:
module.exports = {
name: 'My Wuffle Board',
columns: [
{ name: 'Inbox', label: null },
{ name: 'Backlog', label: 'backlog', sorting: true },
{ name: 'Ready', label: 'ready', sorting: true },
{ name: 'In Progress', label: 'in progress', sorting: true },
{ name: 'Needs Review', label: 'needs review', sorting: true, fifo: true },
{ name: 'Done', label: null, closed: true }
]
};
Checkout a full example for all available options.
Connect repositories that should appear on the board via GitHub.
The board requires you to map some special columns to know how to react to PR opening, issue closing, and so on. The following table shows the states and their mapping to the default column names used above:
State | Default Column |
---|---|
DEFAULT / EXTERNAL_CONTRIBUTION |
Inbox |
IN_PROGRESS |
In Progress |
IN_REVIEW |
Needs Review |
DONE |
Done |
If you would like to use custom-named columns, attach their special state via the states
property:
module.exports = {
name: 'My Wuffle Board',
columns: [
{ name: 'New', label: null, states: [ 'DEFAULT', 'EXTERNAL_CONTRIBUTION' ] },
{ name: 'Doing it', label: 'doing it', states: [ 'IN_PROGRESS' ] },
{ name: 'Review', label: 'review', states: [ 'IN_REVIEW' ] },
{ name: 'Finished', label: null, closed: true, states: [ 'DONE' ] }
]
};
Column mappings enable automatic card movement across the board as you develop.
Per default issues in a column will be ordered last in, first out. This means that, unless they are explicitly sorted into a column, new issues are added on top of existing ones in a column.
To change this to first in, first out mark a column as fifo
. New items will now end up at the bottom of a column. Useful, i.e. for review columns.
In addition to default ordering board columns can be sorted based on semantic issue links. Enable this feature for a column by marking it as sorting
.
Run the app with NODE_ENV=production
to enable strict validation and certain production tweaks.
Instead of relying on a .env
file, you can also pass environment variables directly when starting the app:
NODE_ENV=production APP_ID=YOUR_APP_ID npx wuffle
Pass the board configuration as a JSON encoded string via the BOARD_CONFIG
environment variable.
Hook up Sentry to track errors at run-time.
Read through our configuration section to learn about all available configuration options.
As you move to production, make sure to pass the correct BASE_URL
. Update it on your GitHub app setting page if it changes.
If you use the docker distribution, pass your app configuration via environment variables:
docker run -p 3000:3000 \
-e APP_ID=YOUR_APP_ID \
-e BOARD_CONFIG="{JSON ENCODED BOARD CONFIGURATION}"
-e ... \
nrehwaldt/wuffle:latest
See also: Configuration, Troubleshooting