Run the full Basefloor stack locally — Rails backend, TanStack frontend, and marketing site.

Local Development Setup

This guide gets the entire Basefloor stack running on your local machine.

Prerequisites

Ensure the following are installed:

Tool	Version	Install
Ruby	3.x	`rbenv` or `asdf`
Node.js	18+	`nvm` or system package
PNPM	8+	`npm install -g pnpm`
PostgreSQL	14+	System package or Homebrew
Redis	7+	System package or Homebrew
Git	Any	System package

1. Clone the Repositories

Basefloor uses two separate Git repos:

# Backend
git clone [email protected]:flockworks/hms-core.git
cd hms-core

# Frontend monorepo (new terminal)
git clone [email protected]:flockworks/basefloor-UI.git
cd basefloor-UI

2. Backend Setup (hms-core)

cd hms-core

# Install Ruby dependencies
bundle install

# Set up the database
bin/rails db:create
bin/rails db:migrate
bin/rails db:seed   # Creates sample hotel chains and users

Environment Configuration

Copy the example environment file:

cp config/environments/development.rb.example config/environments/development.rb

Ensure config/master.key is present (get this from a team member or from the shared secrets store).

Start the Backend

# In one terminal: Rails API server
bin/rails server -p 4000

# In another terminal: Background job processor
bin/jobs

The API is now available at http://localhost:4000.

3. Frontend Setup (basefloor-UI)

cd basefloor-UI

# Install all workspace dependencies
pnpm install

# Copy environment file for the web app
cp apps/web/.env.example apps/web/.env

Edit apps/web/.env:

VITE_API_BASE_URL=http://localhost:4000/api/v1

Start the Frontend

# Start all apps
pnpm dev

# Or start individual apps
pnpm dev:web        # TanStack app → http://localhost:3000
pnpm dev:marketing  # Marketing site → http://localhost:3001

4. Subdomain Setup for Local Development

The web app uses subdomains to identify tenants. For local development, use lvh.me — a domain that always resolves to 127.0.0.1:

http://khyber.lvh.me:3000   # Maps to the "khyber" hotel chain
http://demo.lvh.me:3000     # Maps to the "demo" hotel chain

The seed data creates these two chains by default. You can add more in the seed file.

Alternative: /etc/hosts

If lvh.me does not work in your environment:

# Add to /etc/hosts
127.0.0.1 khyber.lvh.me
127.0.0.1 demo.lvh.me

5. Verify the Setup

With both servers running, open your browser:

Visit http://khyber.lvh.me:3000
You should see the Basefloor login page for the Khyber chain
Log in with the seeded credentials (printed in the console during db:seed)

Useful Commands

Backend

bin/rails console          # Rails REPL
bin/rails routes           # List all API routes
bin/rubocop                # Lint Ruby code
bin/brakeman               # Static security analysis
bundle exec rspec          # Run tests

Frontend

pnpm lint                  # ESLint
pnpm type-check            # TypeScript validation
pnpm build                 # Production build
pnpm clean                 # Clear all build artefacts

Troubleshooting

PostgreSQL connection refused Make sure PostgreSQL is running: brew services start postgresql or sudo systemctl start postgresql

Redis not found Start Redis: brew services start redis or sudo systemctl start redis

Subdomain not recognized Check that you are using lvh.me and that the chain slug in your URL matches one seeded in the database.

Bundle install fails on native extensions Ensure you have the appropriate system dependencies: libpq-dev (for the pg gem) and libvips (for image processing).

Local Development Setup

On this page