Skip to main content

Installation

3 min readStableBeginner

OwnDocs is a source purchase. After payment you receive a .zip and a .tar.gz archive of the source: extract one once, then install dependencies with the package manager that matches your target. This page covers the three supported package managers and the exact cleanup steps for switching between them.

The commands below show the archive as owndocs-<version>.zip. Replace <version> with the number in the filename you were sent, for example owndocs-1.0.0.zip. These steps are for a first-time setup. If you already have OwnDocs running somewhere, don't extract a new archive over it; your content and configuration live in that project folder.

Pick a package manager

OwnDocs works with npm, Bun, and pnpm. Which one to choose depends on where you are deploying:

  • npm is the recommended path for Vercel. Vercel detects Next.js and package-lock.json automatically, so npm is the zero-config default.
  • Bun is the recommended path for self-hosted servers. It installs and builds faster, which matters for cold starts on your own infrastructure.
  • pnpm is an equivalent self-hosted option when you already standardize on it.

package-lock.json is the authoritative lockfile in this repository. npm and Vercel both consume it directly.

Prerequisites

  • Node.js 20.9.0 or newer. That is the supported floor, set in package.json. OwnDocs is built and tested on Node.js 24, which is what .nvmrc and the Dockerfile pin, so use 24 unless you have a reason not to.
  • The package manager you picked: npm (ships with Node), bun, or pnpm

Steps

Install with npm

  1. Extract the archive

    Bash
    Bash
    unzip owndocs-<version>.zip
mv owndocs-<version> my-docs
cd my-docs

  2. Generate environment variables

    Bash
    Bash
    bash scripts/setup-env.sh

  3. Install dependencies

    Bash
    Bash
    npm install

  4. Start the development server

    Bash
    Bash
    npm run dev

The site serves at http://localhost:3000.

Install with Bun

  1. Extract the archive and generate environment variables

    Bash
    Bash
    unzip owndocs-<version>.zip
mv owndocs-<version> my-docs
cd my-docs
bash scripts/setup-env.sh

  2. Remove the npm lockfile and install cleanly

    Bash
    Bash
    rm -f package-lock.json
rm -rf node_modules
bun install

  3. Start the development server

    Bash
    Bash
    bun run dev

Install with pnpm

  1. Extract the archive and generate environment variables

    Bash
    Bash
    unzip owndocs-<version>.zip
mv owndocs-<version> my-docs
cd my-docs
bash scripts/setup-env.sh

  2. Remove the npm lockfile and install cleanly

    Bash
    Bash
    rm -f package-lock.json
rm -rf node_modules
pnpm install

  3. Start the development server

    Bash
    Bash
    pnpm run dev

Switch package managers cleanly

Switching managers without cleanup leaves stale lockfiles and duplicate dependency trees, which causes flaky installs and hard-to-trace build failures. Remove the previous manager's lockfile and node_modules/ before a clean install.

  • From npm: remove package-lock.json and node_modules/.
  • From Bun: remove bun.lock or bun.lockb and node_modules/.
  • From pnpm: remove pnpm-lock.yaml and node_modules/.

Then run the target manager's install command. package-lock.json is the repository's canonical lockfile, so npm and Vercel treat it as authoritative; the other lockfiles are manager-local and safe to regenerate.

Result

After install, the development server runs at http://localhost:3000 with the environment variables generated by scripts/setup-env.sh. Continue to Deployment to go live.

Related pages

Deployment

Configuration

Was this page helpful?

© 2026 DevOps. All rights reserved.