Codakey
Play
← Back to 255kb/stack-on-a-budget

How to Deploy & Use 255kb/stack-on-a-budget

Stack on a Budget - Deploy & Usage Guide

Prerequisites

  • Git (2.0+) for version control
  • Text Editor with Markdown support (VS Code, Typora, or similar)
  • GitHub Account (required for contributing or deploying via GitHub Pages)
  • Optional: Ruby 2.5+ and Bundler (only if running Jekyll locally for site preview)
  • Optional: Node.js 14+ (only if using markdown linting tools)

Installation

Clone the Repository

git clone https://github.com/255kb/stack-on-a-budget.git
cd stack-on-a-budget

Optional: Local Jekyll Setup (for GitHub Pages preview)

If you want to preview the site locally as it appears on GitHub Pages:

# Install dependencies (if Gemfile exists)
bundle install

# If no Gemfile, install Jekyll directly
gem install jekyll bundler

Configuration

Repository Structure

The project uses the following structure:

  • README.md - Main table of contents and entry point
  • pages/*.md - Individual service category documentation
  • CONTRIBUTING.md - Contribution guidelines and service selection rules

For GitHub Pages Deployment

If deploying to GitHub Pages, ensure your repository settings:

  1. Go to Settings > Pages
  2. Set Source to deploy from the main branch (root or /docs folder)
  3. No additional configuration files required for basic Markdown rendering

Build & Run

Development Mode (Local Preview)

Option 1: Direct Markdown Reading Simply open the .md files in your text editor or Markdown previewer. No build step required.

Option 2: Jekyll Local Server (if supporting GitHub Pages features)

bundle exec jekyll serve

# Access at http://localhost:4000/stack-on-a-budget/

Option 3: Static File Server (for raw HTML preview)

# Using Python
python -m http.server 8000

# Using Node.js npx
npx serve .

Production Build

For Jekyll-based deployment:

JEKYLL_ENV=production bundle exec jekyll build
# Output will be in `_site/` directory

Deployment

Option 1: GitHub Pages (Recommended)

  1. Fork the repository to your GitHub account
  2. Navigate to Settings > Pages
  3. Enable GitHub Pages from the main branch
  4. Your site will be available at https://<username>.github.io/stack-on-a-budget/

Option 2: Netlify

  1. Connect your GitHub repository to Netlify
  2. Build settings:
    • Build command: jekyll build (or leave empty for pure Markdown)
    • Publish directory: _site/ (or root if no build)
  3. Deploy automatically on git push

Option 3: Vercel

  1. Import the project to Vercel
  2. Framework preset: Other
  3. Build command: None (static Markdown files)
  4. Output directory: ./ (root)

Option 4: Raw Repository Usage

No deployment necessary. Users can simply browse the documentation directly on GitHub at https://github.com/255kb/stack-on-a-budget.

Usage

Browsing Services

Navigate to the specific category files in the pages/ directory:

  • pages/app-hosting.md - Hosting providers
  • pages/database-hosting.md - Database services
  • pages/continuous-integration-delivery.md - CI/CD tools

Contributing New Services

  1. Review CONTRIBUTING.md for service selection criteria
  2. Add the service to the appropriate category file in pages/
  3. Include specific free tier details and limitations
  4. Update the main README.md table of contents if adding a new category
  5. Submit a Pull Request

Content Guidelines

When adding services, include:

  • Free tier specifications (limits, quotas, expiration)
  • Limitations (sleeping apps, credit card requirements)
  • Sponsorship disclosure (note that Mockoon sponsors this list)

Troubleshooting

Broken Internal Links

If links between pages fail:

  • Ensure links use relative paths: pages/activity-feeds.md#pubnub
  • Check that anchor links match header IDs (lowercase, hyphenated)

Markdown Rendering Issues

Problem: Tables or HTML divs not rendering correctly
Solution: Ensure your Markdown parser supports GitHub Flavored Markdown (GFM). Use kramdown with GFM if using Jekyll.

Problem: Images not displaying
Solution: Check that image paths are relative to the repository root. The Mockoon sponsor image uses an absolute URL.

Jekyll Build Errors

Error: Liquid Exception: Could not locate the included file
Fix: Ensure all includes referenced in templates exist in the _includes/ directory (if present).

Error: Gem::LoadError
Fix: Run bundle install to install missing dependencies.

Contribution Rejections

If your PR is rejected:

  • Verify the service meets the free tier criteria in CONTRIBUTING.md
  • Ensure you've disclosed any affiliation with the service
  • Check that the free tier is genuinely useful for developers (not just a short trial)

Local Preview Not Matching GitHub

Issue: Local Jekyll rendering differs from GitHub Pages
Fix: Use the github-pages gem in your Gemfile to match GitHub's exact build environment:

gem 'github-pages', group: :jekyll_plugins
← Project overviewView alternatives to 255kb/stack-on-a-budget →