Kaizen NetworkSoftware

Cloudshort

Installation

Set up Cloudshort on your Cloudflare account, connect your domains, and log in for the first time.

This takes about 15 minutes. You run a few commands on your computer, and the setup script creates everything on Cloudflare for you.

1. Get the tools

You type the commands in this guide into a terminal: Terminal on macOS and Linux, or PowerShell on Windows. Open it in the folder where you want Cloudshort to live.

You need these on your computer:

  • Node.js 22 or newer. Check with node -v.
  • pnpm. Check with pnpm -v.
  • Git, to download the code.

You also need a Cloudflare account.

2. Download Cloudshort

git clone https://github.com/kaizen-network/cloudshort.git
cd cloudshort
pnpm install

3. Log in to Cloudflare

npx wrangler login

A browser window opens. Log in and allow access. Wrangler is Cloudflare's command line tool, and it was installed by pnpm install.

4. Run the setup

pnpm run project:setup

The script:

  1. Creates a D1 database named cloudshort-db and a KV namespace named LINKS_KV, or finds them if they already exist.
  2. Writes apps/redirector/wrangler.toml and apps/dashboard/wrangler.toml with their IDs. These files are yours and are not part of the repository.
  3. Creates the database tables.
  4. Creates a Pages project named cloudshort-dashboard.
  5. Asks you for an admin password (at least 12 characters, typed twice). Nothing shows on screen while you type it. This is the password for the dashboard.
  6. Creates a random secret for login sessions.

You can run the setup again at any time. It does not delete anything, and it asks before changing your password.

5. Deploy

pnpm run project:deploy

This uploads the redirector and the dashboard. On a new Cloudflare account, it may first ask to set up a workers.dev subdomain; answer yes. When it finishes, it prints two addresses:

  • the redirector, at https://cloudshort-redirector.<your-account>.workers.dev
  • the dashboard, at an address ending in .pages.dev

6. Connect your domains

Short links look best on a short domain. The domain has to be added to your Cloudflare account first (how to add a site).

In the Cloudflare dashboard:

  1. Go to Workers & Pages, open cloudshort-redirector, then Settings > Domains & Routes > Add > Custom domain. Enter your short domain, for example s.example.com.
  2. Go back to Workers & Pages, open cloudshort-dashboard, then Custom domains > Set up a custom domain. Enter your admin domain, for example admin.example.com.

Cloudflare sets up the DNS records and certificates for you. It can take a few minutes.

7. First login

  1. Open your admin domain (or the .pages.dev address from step 5) and log in with the password from step 4.
  2. Go to Settings and set Short Link Domain to your short domain, for example https://s.example.com. The copy buttons then give you the right links.
  3. Create your first link. See Using the dashboard.

Setting up by hand

If you prefer not to use the setup script, the same steps by hand:

npx wrangler d1 create cloudshort-db
npx wrangler kv namespace create LINKS_KV

Copy apps/redirector/wrangler.example.toml to apps/redirector/wrangler.toml, and apps/dashboard/wrangler.example.toml to apps/dashboard/wrangler.toml. In both files, replace YOUR_KV_ID and YOUR_D1_ID with the IDs the two commands printed. Then:

npx wrangler d1 migrations apply cloudshort-db --remote --config apps/redirector/wrangler.toml
npx wrangler pages project create cloudshort-dashboard --production-branch main
npx wrangler pages secret put ADMIN_PASSWORD --project-name cloudshort-dashboard
npx wrangler pages secret put JWT_SECRET --project-name cloudshort-dashboard
pnpm run project:deploy

For JWT_SECRET, use a long random value, for example the output of node -e "console.log(require('crypto').randomBytes(32).toString('hex'))".

Something not working? See Troubleshooting.