Install Shoot Desk step by step.

This guide is written for someone who has never installed a web app before. Start with Netlify if you want the easiest private hosted version. Local hosting is still included below for people who want to run it from their own computer or server.

Start with Netlify Use local hosting

Choose your path

For most people, Netlify is the simpler install because it gives you hosting, HTTPS, and an always-on URL without keeping your own computer running.

Netlify install

Best for most first-time installs. Netlify builds the Next.js app, hosts it with HTTPS, and stores production data with Netlify Blobs.

Deploy to Netlify

Local install

Best when you want to test Shoot Desk on your own computer or run it from a server you manage. It only works while the app is running.

Use local hosting

Netlify install

Use this when you want Shoot Desk online behind your own login. Netlify reads the Shoot Desk source from GitHub, builds the app, and gives you a hosted URL.

Create or sign in to GitHub and Netlify

You need GitHub to access the Shoot Desk source code and a Netlify account for hosting. Signing in to Netlify with GitHub is the simplest path.

GitHub repo: github.com/JustinMDigital/shoot-desk
Netlify: app.netlify.com

Create a Netlify-ready copy of the source

Open the Shoot Desk repo on GitHub and click Fork. A fork is just a copy of the app source so Netlify can build it from your account. Your login settings and workspace data are added in later steps.

Use the release branch for installs. Do not deploy from main; main is the active development branch and may include unfinished changes.

Create a Netlify project from Git

In Netlify, choose Add new project, then Import an existing project, then connect GitHub and select your Shoot Desk fork. In the deploy settings, set the production branch to release.

If Netlify asks for build settings, use the values already in netlify.toml:

Build command: npm run build
Publish directory: .next
Node version: 22

Add required environment variables

Before using the site, add these variables in Netlify under Site configuration or Project configuration, then Environment variables.

APP_USERNAME

The private username for the Shoot Desk login screen.

APP_PASSWORD

A long password. Do not reuse an important personal password.

AUTH_SECRET

A long random value used to sign the app login cookie.

Generate an auth secret locally if you have Node installed:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Add hosted login settings here, in Netlify environment variables. This is how the deployed site gets its username, password, and auth secret.

Add optional workspace defaults

These are not required for the app to boot, but they make invoices and the public gear list feel like yours before you start editing inside the app.

WORKSPACE_NAME, WORKSPACE_OWNER_NAME, WORKSPACE_EMAIL
WORKSPACE_CHECK_PAYABLE_TO, WORKSPACE_ZELLE, WORKSPACE_VENMO
PUBLIC_GEARLIST_BRAND_NAME, PUBLIC_GEARLIST_CONTACT_EMAIL, PUBLIC_GEARLIST_INTRO

The full list lives in .env.example. Leave blank any field you do not use.

Deploy and log in

Trigger a deploy in Netlify. When the deploy finishes, open the Netlify URL. You should land on the Shoot Desk login page.

Workspace app: your Netlify site root URL.
Public gear list: add /gearlist to the end of the URL.
Login with APP_USERNAME and APP_PASSWORD.

If you added environment variables after the first failed deploy, trigger another deploy so Netlify rebuilds with the new settings.

Local install

Use this path when you want Shoot Desk on your own computer or a server you manage. Run each command in Terminal on macOS or PowerShell on Windows.

Install the basic tools

Install Node.js 22 and Git. Node runs the app. Git downloads the repo. npm comes bundled with Node.

Node.js: nodejs.org
Git: git-scm.com/downloads

After installing, close and reopen Terminal so the new commands are available.

Download the app from GitHub

Pick a folder where you keep projects, then clone the public repository. Cloning means Git downloads the app files to your computer.

git clone --branch release https://github.com/JustinMDigital/shoot-desk.git
cd shoot-desk

If Terminal says git is not found, Git is not installed or Terminal needs to be reopened.

Install the app dependencies

Dependencies are the packages Shoot Desk needs to run. This can take a few minutes the first time.

npm install

Create your private login settings

Copy the example environment file, then edit the new .env.local file. This file stays on your computer and supplies the local login screen.

cp .env.example .env.local

On Windows PowerShell, use this instead:

copy .env.example .env.local

Set these values inside .env.local:

APP_USERNAME: the username you type on the login screen.
APP_PASSWORD: a long private password.
AUTH_SECRET: a random secret used to sign login cookies.

Generate an auth secret with Node:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Create your workspace profile

Copy the private app config example. Then edit private-app-config.json with your name, email, invoice defaults, payment fields, and public gear-list text.

cp private-app-config.example.json private-app-config.json

On Windows PowerShell, use this instead:

copy private-app-config.example.json private-app-config.json

Keep .env.local, private-app-config.json, and anything in data/ on your computer. They can contain private contact, payment, address, login, and workspace data.

Run Shoot Desk

Start the development server:

npm run dev

Open http://localhost:3000 in your browser. Log in with the APP_USERNAME and APP_PASSWORD you set.

If you see the Shoot Desk login page, the local install worked.

Local installs are only available while the app is running. If you close Terminal, shut down the computer, or the port is blocked, the webpage will not load. To reach it from another device or away from home, either deploy to Netlify or keep the computer running and intentionally expose the app through a port, router rule, or secure tunnel.

Optional data migration

Skip this for a fresh install. Use it only when you already have local Shoot Desk data and want that same data inside a Netlify site.

Export local data

Run this from the local Shoot Desk folder. It creates an ignored export file.

npm run data:export

Preview the import

This checks what would be written without touching Netlify.

npm run data:import:blobs -- --dry-run

Import into Netlify Blobs

Set NETLIFY_SITE_ID and NETLIFY_AUTH_TOKEN locally, then run the import. Keep the token only in your local Terminal session or local environment.

npm run data:import:blobs

Troubleshooting

Most first-time problems are missing tools, commands run from the wrong folder, or environment variables that were never added to Netlify.

git is not found: install Git, then reopen Terminal.
node or npm is not found: install Node.js 22, then reopen Terminal.
npm install fails: make sure you are inside the shoot-desk folder.
The local page will not open: check that npm run dev is still running and open http://localhost:3000.
The local page worked earlier but stopped: restart npm run dev. Local installs are not always-on websites unless the computer stays awake and the app keeps running.
You want access from another device or location: use Netlify, or deliberately open/forward a port or use a secure tunnel. Do not expose the app publicly with a weak password.
Netlify deploy fails: check the deploy log first, then confirm the build command is npm run build and the publish directory is .next.
Login does not work: confirm APP_USERNAME, APP_PASSWORD, and AUTH_SECRET are set in the same place the app is running.

Official references: GitHub cloning guide, Next.js on Netlify, Netlify environment variables, and Netlify Git deploys.