Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .dockerignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
.git
.github
vendor
.var
.cache
www.pid
44 changes: 44 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
name: Build and test

on:
push:
pull_request:
workflow_dispatch:

permissions:
contents: read

jobs:
hack:
runs-on: ubuntu-24.04
timeout-minutes: 20
env:
COMPOSE_PROJECT_NAME: hack-dev-ci
PORT: 18080
steps:
- uses: actions/checkout@v7.0.1
- name: Match the workspace owner
run: echo "HACK_UID=$(id -u)" >> "$GITHUB_ENV"
- name: Validate Compose and build the image
run: |
docker compose config --quiet
docker compose build --pull
- name: Install dependencies and check Hack
run: |
docker compose run --rm --no-deps hack-dev-ubuntu sh -eu -c '
composer install --prefer-dist --no-progress
composer validate --no-check-publish
composer check-platform-reqs
composer test
composer lint
composer typecheck
'
- name: Check the HTTP endpoint
run: |
docker compose up -d --wait --wait-timeout 240
test "$(curl --fail --silent http://127.0.0.1:18080/hello.hack)" = 'Hello World!'
- name: Show logs and clean up
if: always()
run: |
docker compose logs --no-color
docker compose down
4 changes: 2 additions & 2 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
vendor/
www.pid
Dockerfile
.var/
.var/
.cache/
48 changes: 48 additions & 0 deletions Dockerfile
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
# syntax=docker/dockerfile:1
# HHVM's last published distro package requires Ubuntu 20.04 libraries.
FROM ubuntu:20.04

ARG TARGETARCH
ARG COMPOSER_VERSION=2.11.1
ARG COMPOSER_SHA256=6f1b891e1d4927d62740276c540fb490e47689e19e102c49e8da849794882f8c

ENV HHVM_DISABLE_NUMA=true \
HHVM_DISABLE_PERSONALITY=true \
COMPOSER_NO_INTERACTION=1

RUN test "$TARGETARCH" = amd64 \
&& apt-get update \
&& DEBIAN_FRONTEND=noninteractive apt-get upgrade -y \
&& DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
ca-certificates curl git lsof php-cli php-curl php-mbstring php-xml unzip \
&& rm -rf /var/lib/apt/lists/*

# dl.hhvm.com's HTTPS certificate has expired. Verify the frozen package by
# its published SHA-256 instead of disabling TLS verification for downloads.
RUN curl -fL --retry 3 \
http://dl.hhvm.com/ubuntu/pool/main/h/hhvm/hhvm_4.172.1-1~focal_amd64.deb \
-o /tmp/hhvm.deb \
&& echo 'ee567aa0f7eee3c00a73e9265fdd3998c9b3c40b60028c236ed93933abe67763 /tmp/hhvm.deb' | sha256sum -c - \
&& apt-get update \
&& DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends /tmp/hhvm.deb \
&& rm -rf /tmp/hhvm.deb /var/lib/apt/lists/*

ARG HACK_UID=1000
RUN curl -fL --retry 3 "https://getcomposer.org/download/${COMPOSER_VERSION}/composer.phar" \
-o /usr/local/bin/composer \
&& echo "${COMPOSER_SHA256} /usr/local/bin/composer" | sha256sum -c - \
&& chmod +x /usr/local/bin/composer \
&& useradd --create-home --uid "$HACK_UID" --shell /bin/bash hack \
&& mkdir /app \
&& chown hack:hack /app

COPY docker/entrypoint.sh /usr/local/bin/docker-entrypoint
COPY docker/hhvm.ini /etc/hhvm/php.ini
RUN chmod +x /usr/local/bin/docker-entrypoint

WORKDIR /app
COPY --chown=hack:hack . /app
USER hack
EXPOSE 8080
ENTRYPOINT ["docker-entrypoint"]
CMD ["hhvm", "-m", "server", "-p", "8080", "-d", "hhvm.server.source_root=/app/src"]
150 changes: 139 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,20 +1,148 @@
# What is this?
A way to get [HHVM](https://hhvm.com/) working on arm64.
# Docker Hack development environment

# How to use
This requires use of [Colima](https://github.com/abiosoft/colima) and an up to date version of [QEMU](https://www.qemu.org/) in order to work. Rosetta does not currently support [some x86_64 instruction](https://developer.apple.com/documentation/apple-silicon/about-the-rosetta-translation-environment) execution which HHVM uses.
A Docker-based [HHVM](https://hhvm.com/) development image, including Composer,
the Hack typechecker and linter, and HackTest. The image is built from the tracked
Dockerfile; source and dependencies are mounted at `/app` during development.

## Version limits

Verified against upstream package indexes on November 3, 2026:

| Component | Version |
| --- | --- |
| HHVM | 4.172.1 (last published Ubuntu package) |
| Ubuntu | 20.04, with all available public package updates |
| PHP (runs Composer only) | Ubuntu's 7.4 package, with available public updates |
| Composer | 2.11.1 |
| HSL | 4.108.1 |
| hhvm-autoload | 3.3.2 |
| hh-clilib | 2.6.0 |
| HackTest | 2.4.0 |
| FBExpect | 2.9.1 |

These are the latest available packages for this environment, **not a currently
maintained runtime stack**. HHVM [ended official releases](https://hhvm.com/blog/2023/10/27/oss-update.html).
The newer [HHVM 4.172.3 source tag](https://github.com/facebook/hhvm/tree/HHVM-4.172.3)
has no corresponding official Ubuntu package or Docker image. Later security
fixes [require compiling HHVM from source](https://hhvm.com/blog/2023/07/25/security-update.html).
Ubuntu 20.04's normal support has ended, and several Hack tools are marked
abandoned. This setup is for local development; rebuilding it does not make
those unsupported components current or suitable for public deployment.

The packaged HHVM binary depends on Ubuntu 20.04 libraries, so simply changing
the base image to a newer Ubuntu release will not work. Its download is pinned
by SHA-256 because `dl.hhvm.com` currently has an expired HTTPS certificate;
Composer downloads continue to use HTTPS and are also checksum-verified.

HHAST was removed because even its last release (4.168.3) rejects HHVM 4.172's
syntax-tree schema. `composer lint` uses HHVM's built-in `hh_client --lint`
instead. This checks Hack diagnostics; HHAST-specific style rules are no longer
available. `HHVM_DISABLE_PERSONALITY=true` lets the typechecker work with Docker's
default seccomp profile without changing container security settings.

## Start the environment

Install Docker Engine/Desktop and Docker Compose v2 or newer. On x86-64 Linux
or an Intel Mac, use your normal Docker context. On Apple Silicon, use a full
x86-64 QEMU VM with Colima. Setting `platform: linux/amd64` alone is not enough:
the CLI tools can work under Docker Desktop's translation while the HTTP server
still crashes. This build's full test suite, including HTTP, is verified on
native x86-64 Linux in CI; the full Colima VM path has not been revalidated here.

```sh
brew install docker docker-compose qemu colima
```
brew install docker
brew install qemu
brew install colima

For an existing Homebrew installation, first run
`brew update && brew upgrade docker docker-compose qemu colima`, then start the VM:

```sh
colima start --profile hack-dev --vm-type qemu --arch x86_64 \
--cpu 4 --cpu-type max --memory 16 --network-address
docker context use colima-hack-dev
```

If Homebrew's Compose plugin is not found, follow the plugin setup printed by
`brew info docker-compose`. Use a separate Colima profile so other VMs are not
reconfigured. Stop this VM with `colima stop --profile hack-dev` when finished.

```sh
git clone https://github.com/justdan6/docker-hack-dev.git
cd docker-hack-dev
# On Linux, match the bind-mounted directory's owner:
# export HACK_UID=$(id -u)
docker compose build --pull
docker compose up -d --wait --wait-timeout 240
```

Open <http://localhost:8080/hello.hack>. The expected response is `Hello World!`.
Changes in `src/` are picked up without rebuilding the image. Composer installs
the committed lockfile before the server starts and stops startup on failure.
The service runs as the `hack` user, and the port is bound to localhost.
Set `PORT=8081` before `docker compose up` to use a different host port.

colima start --arch x86_64 --cpu 4 --cpu-type "max" --memory 16 --network-address
docker compose up
## Update and rebuild

After pulling updated repository files:

```sh
git pull --ff-only
docker compose build --pull --no-cache
docker compose up -d --force-recreate --wait --wait-timeout 240
docker compose exec hack-dev-ubuntu composer test
```

`--pull` refreshes the Ubuntu base image; `--no-cache` reruns package installation
to pick up available OS updates. `up --force-recreate` replaces the running
container with the rebuilt image. The bind-mounted source and `vendor/` remain
on your host. No volume deletion is needed.

To look for future Hack library updates, then regenerate and commit the lockfile:

```sh
docker compose run --rm --no-deps hack-dev-ubuntu composer outdated --direct
docker compose run --rm --no-deps hack-dev-ubuntu composer update --with-all-dependencies
```

Go to http://localhost:8080/hello.hack
Composer itself is pinned in `Dockerfile`. To update it later, change
`COMPOSER_VERSION` and `COMPOSER_SHA256` together using the checksum from the
[official downloads page](https://getcomposer.org/download/), then rebuild.
Update Docker Desktop through its updater, or update Docker Engine and the
Compose plugin through your OS package manager.

## Validate the build

```sh
docker compose run --rm --no-deps hack-dev-ubuntu composer install --prefer-dist
docker compose run --rm --no-deps hack-dev-ubuntu composer validate --no-check-publish
docker compose run --rm --no-deps hack-dev-ubuntu composer check-platform-reqs
docker compose run --rm --no-deps hack-dev-ubuntu composer test
docker compose run --rm --no-deps hack-dev-ubuntu composer lint
docker compose run --rm --no-deps hack-dev-ubuntu composer typecheck
curl --fail http://localhost:8080/hello.hack
```

GitHub Actions runs the build, dependency checks, tests, lint, typecheck, and
HTTP smoke test on x86-64 Linux for pushes and pull requests.

Inspect failures with `docker compose logs --tail=100`; stop the environment
with `docker compose down`. If APT reports invalid signatures during a build,
also check that Docker's VM has free disk space.
If a macOS bind mount fails with `operation not permitted`, grant Docker Desktop
access to the checkout's directory in macOS privacy/file-sharing settings, or
move the checkout into a directory Docker can already access.

## Publish the rebuilt image

Building locally does not update Docker Hub. If you maintain
`justdanz/hack-dev-ubuntu`, publish the tested image explicitly:

```sh
docker login
docker compose push hack-dev-ubuntu
```

Any changes in /src will be picked up by [HHVM](https://docs.hhvm.com/hhvm/).
To publish under a different Docker Hub account, change `image:` in
`compose.yaml` before building and pushing. This repository does not push images
automatically. Compose normally builds from source (`pull_policy: build`), so
`docker compose pull` alone is not the update workflow for this checkout.
24 changes: 16 additions & 8 deletions compose.yaml
Original file line number Diff line number Diff line change
@@ -1,13 +1,21 @@
services:
hack-dev-ubuntu:
image: justdanz/hack-dev-ubuntu # justdanz/hack-dev-debian
image: justdanz/hack-dev-ubuntu:latest
platform: linux/amd64
build:
context: .
args:
HACK_UID: ${HACK_UID:-1000}
pull_policy: build
init: true
working_dir: /app
volumes:
- ./:/app
ports:
- "8080:8080"
command:
- /bin/sh
- -c
- |
composer install
hhvm -m server -p 8080 -d hhvm.server.source_root=/app/src
- "127.0.0.1:${PORT:-8080}:8080"
healthcheck:
test: ["CMD", "curl", "--fail", "--silent", "http://127.0.0.1:8080/hello.hack"]
interval: 10s
timeout: 5s
retries: 6
start_period: 120s
17 changes: 11 additions & 6 deletions composer.json
Original file line number Diff line number Diff line change
@@ -1,17 +1,22 @@
{
"require": {
"hhvm/hsl": "^4.108",
"hhvm/hhvm-autoload": "^3.3",
"facebook/hh-clilib": "^2.6"
"hhvm": "~4.172.1",
"hhvm/hsl": "^4.108.1",
"hhvm/hhvm-autoload": "^3.3.2",
"facebook/hh-clilib": "^2.6.0"
},
"config": {
"allow-plugins": {
"hhvm/hhvm-autoload": true
}
},
"require-dev": {
"hhvm/hhast": "^4.168",
"hhvm/hacktest": "^2.4",
"facebook/fbexpect": "^2.9"
"hhvm/hacktest": "^2.4.0",
"facebook/fbexpect": "^2.9.1"
},
"scripts": {
"test": "vendor/bin/hacktest tests/",
"lint": "php scripts/lint.php",
"typecheck": "hh_client check"
}
}
Loading