Hiring Without Whiteboards - Deployment & Usage Guide

Prerequisites

• Node.js (v16.x or higher) and npm (v8.x or higher)
• Git (v2.30 or higher)
• Airtable account (for database integration)
• GitHub account (for contributions and webhooks)
• Text editor with Markdown linting support (VS Code recommended)

Installation

1. Clone the Repository

git clone https://github.com/poteto/hiring-without-whiteboards.git
cd hiring-without-whiteboards

2. Install Linting Dependencies

npm install

3. Clone the API Repository (Optional)

For Airtable integration functionality:

git clone https://github.com/poteto/hww-api.git
cd hww-api
npm install

Configuration

Environment Variables

Create a .env file in the hww-api directory:

AIRTABLE_API_KEY=your_airtable_api_key
AIRTABLE_BASE_ID=your_base_id
AIRTABLE_TABLE_NAME=Companies
GITHUB_WEBHOOK_SECRET=your_webhook_secret
PORT=3000

Airtable Setup

1. Create a new base in Airtable

2. Create a table named "Companies" with the following fields:

   • Name (Single line text)
   • URL (URL)
   • Location (Single line text)
   • Description (Long text)
   • Keywords (Multiple select)

3. Generate an API key from your Airtable account settings

GitHub Webhook Configuration

1. Go to repository Settings > Webhooks > Add webhook
2. Payload URL: https://your-api-domain.com/webhook
3. Content type: application/json
4. Secret: Match your GITHUB_WEBHOOK_SECRET env variable
5. Events: Select "Pull requests"

Build & Run

Linting the Main Repository

Validate Markdown formatting and company entries:

npm run lint

Auto-fix linting errors:

npm run lint:fix

Running the API Locally (Development)

cd hww-api
npm run dev

The API will be available at http://localhost:3000

Production Build for API

cd hww-api
npm run build
npm start

Deployment

Deploying the API (Node.js)

Option 1: Vercel (Recommended)

npm i -g vercel
cd hww-api
vercel --prod

Configure environment variables in Vercel dashboard.

Option 2: Heroku

cd hww-api
heroku create hww-api
git push heroku main
heroku config:set AIRTABLE_API_KEY=your_key

Option 3: Docker

Create a Dockerfile in hww-api:

FROM node:16-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
EXPOSE 3000
CMD ["npm", "start"]

Build and run:

docker build -t hww-api .
docker run -p 3000:3000 --env-file .env hww-api

Static Site Deployment (GitHub Pages)

The main repository auto-renders on GitHub. To enable custom domain:

1. Add a CNAME file with your domain
2. Configure DNS to point to GitHub Pages
3. Enable HTTPS in repository settings

Airtable Automation

The webhook integration automatically syncs merged PRs to Airtable. Ensure:

• GitHub webhook is active
• API service is running and accessible
• Airtable API key has write permissions

Troubleshooting

Linting Errors

Issue: remark-lint errors on company entries Solution: Ensure entries follow the format:

- [Company Name](https://url.com/careers) | Location | Description

Run npm run lint:fix to auto-correct formatting.

Airtable Sync Failures

Issue: Webhook returns 500 error Check:

1. Verify AIRTABLE_API_KEY is valid and not expired
2. Confirm AIRTABLE_BASE_ID matches your base URL
3. Check that table name "Companies" exists with correct schema
4. Review logs: heroku logs --tail or vercel logs

GitHub Webhook Not Triggering

Issue: PR merges not syncing to Airtable Solution:

1. Verify webhook secret matches between GitHub and env variable
2. Check payload URL is correct and SSL certificate is valid
3. Ensure "Pull requests" event is selected in webhook settings
4. Test with a sample PR: curl -X POST -H "Content-Type: application/json" -d '{"action":"closed","pull_request":{"merged":true}}' https://your-api/webhook

CORS Errors

Issue: Frontend cannot access API Solution: Add CORS headers in hww-api middleware:

app.use((req, res, next) => {
  res.header('Access-Control-Allow-Origin', '*');
  res.header('Access-Control-Allow-Headers', 'Origin, X-Requested-With, Content-Type, Accept');
  next();
});

Rate Limiting

Issue: Airtable API rate limits exceeded (5 requests per second) Solution: Implement request queuing or caching in the API layer. Use a Redis cache for read operations to reduce Airtable API calls.