HungryHub Server

Quick Start

Option 1: VS Code Dev Container (Recommended)

The fastest way to get started is using VS Code with Dev Containers:

  1. Prerequisites: Install VS Code and Docker

  2. Open in Dev Container:

“`bash # Clone the repository git clone github.com/hungryhub-team/hh-server.git cd hh-server

# Open in VS Code code .

# When prompted, click “Reopen in Container” # OR press Ctrl/Cmd+Shift+P and search “Dev Containers: Reopen in Container” “`

  1. Wait for setup: The dev container will automatically:

  2. Set up Ruby, Node.js, and system dependencies

  3. Configure the environment using ./bin/setup_env.sh local

  4. Start all required services (MySQL, Redis, Memcached, MongoDB)

  5. Install gems and npm packages

  6. Set up the database schema

  7. Start developing: Once the container is ready, you can immediately run:

bash bundle exec rails server

Why use Dev Containers?

  • ✅ Instant setup: No need to install Ruby, Node.js, MySQL, Redis locally

  • ✅ Consistent environment: Same setup for all developers

  • ✅ Isolated: Won't conflict with other projects on your machine

  • ✅ Pre-configured: All services and tools ready to use

Option 2: Manual Setup

See documentation in kb.hungryhub.com

Environment Configuration System

The project uses a base + override system to avoid duplication:

  • .env.example - Complete base configuration (~200 variables)

  • .env.ci - CI-specific overrides only (~13 variables)

  • ./bin/merge_env.sh - Merges base + overrides → .env

Quick environment setup commands:

./bin/setup_env.sh local    # Local development (dev container/docker-compose)
./bin/setup_env.sh ci       # CI/test environment
./bin/setup_env.sh staging  # Staging environment (if .env.staging exists)
./bin/setup_env.sh clean    # Clean base configuration only

See Environment Configuration Guide for details.

Development with Kafka on Local Machine

We use hosted Kafka in Aiven, so there's no need to run Kafka locally. We embed the Karafka engine with Sidekiq. You need to run a Sidekiq server for any features that depend on Kafka.

Setup

Create the required Kafka topics:

bundle exec karafka topics create

Monitoring

View logs in separate terminal windows:

tail -f log/development.log
tail -f log/sidekiq.log

Debugging

Access the following admin interfaces:

On the Mirage admin page, use the test button to verify Kafka integration.

With Karafka Pro, you can:

Web Servers

Passenger vs Puma

  • Passenger: Very fast reload time, slower startup time. Does not work with Pry gem.

  • Puma: Use this if you need to use the Pry gem during development.

How to Run the App

With Passenger

bundle exec rails server

With Puma

bundle exec rails server puma

Testing with RSpec

  1. Update the schema and database:

bundle exec rake db:migrate:with_data
bundle exec rails db:test:prepare

  1. Run the tests:

bundle exec rspec

  1. If RSpec is not working, run:

bin/rails db:migrate RAILS_ENV=test

See the handbook space in ClickUp for more information.

To import the database, run:

SET FOREIGN_KEY_CHECKS=0;

Remaking the hh-engineering Branch

Currently, the config for running this app on the DigitalOcean cluster is not properly written in the manifest folder; it's in the hh-engineering branch. To remake the hh-engineering branch based on the main branch, cherry-pick the following configurations:

git checkout hh-engineering
# Make a backup of the current branch
git checkout -b hh-engineering-backup
git push origin hh-engineering-backup

git branch -D hh-engineering
git checkout main
git checkout -b hh-engineering
git cherry-pick 58f2e25
git cherry-pick 5e87c6c
git cherry-pick 8c9fba7
git push origin hh-engineering

Image Proxy / Image Resizing Service

We use imgproxy.net to resize images on the fly. The service is hosted on our own server. To develop the service locally, run:

docker run -p 8080:8080 -it ghcr.io/imgproxy/imgproxy:latest

Update the .env file:

IMGPROXY_ENDPOINT=http://localhost:8080

Run ngrok to expose your Rails server to the internet, so imgproxy can access it:

CDN_URL=http://xxxx.ngrok.app
ENABLE_CDN=true

If the image is empty and you are trying to upload an image while ENABLE_CDN is true, Rails expects that it connects to AWS S3. Ensure the image files already exist in the public folder so imgproxy can resize them.

Opensearch and Kibana

We use Opensearch and Kibana to monitor the logs. To run the service locally, use:

docker compose -f manifest/development/docker-compose.yml up

Then open http://localhost:5601 to access Kibana.

Feature Flags

Glossary

External Systems and Partners

KlickDigital

KlickDigital is our agency partner that enables us to connect with the Dianping Meituan system. Order IDs from KlickDigital are prefixed with 'KD' in our system, and the TicketTransaction.klick_digital_client_order_id? method is used to identify these orders.

Mirage

This is a new service that we will separate from this app.