chore: Container builds

Makefile

@@ -6,6 +6,14 @@ build-and-push-daemon:
 build-daemon:
 	bash scripts/build-daemon.sh
 
+.PHONY: build-migrator
+build-migrator:
+	bash scripts/build-migrator.sh
+
+.PHONY: build-service
+build-service:
+	bash scripts/build-service.sh
+
 .PHONY: push-daemon
 push-daemon:
 	bash scripts/push-daemon.sh

README.md

@@ -113,3 +113,25 @@ mysql -u <user> -p <database> < cleanup.sql
 ```
 
 After cleaning the database, you can reseed the HTR token as described in the previous section.
+
+## Running Inside Containers
+When running these applications inside containers, it's worth noting that there are a few Dockerfiles in this monorepo.
+
+### 1) The Daemon container
+This Dockerfile is located at `./packages/daemon` and is used to build the sync daemon image. It, however,needs a properly migrated database and all the fullnode identifiers to run correctly.
+
+The fullnode identifiers may be fetched dynamically at startup with the use of the `FETCH_FULLNODE_IDS` environment variable, provided the remaining fullnode connection config is available. Please note that this dynamic fetching is only recommended in development environments, as the identifiers are an additional security measure on production builds.
+
+Its image can be build using the `make build-daemon` while on the root folder.
+
+### 2) The Migrator container
+The Migrator Dockerfile is located at `./db` and is used to build the migrator image then shut off. This image is responsible for applying database migrations to the database connection passed through the environment variables.
+
+It's specially important if the database has just been created by the dockerized environment, in which case run this migrator container before starting the daemon. This, again, is only expected in discardable development environments, as production and other more persistent databases should be managed externally.
+
+Its image can be build using the `make build-migrator` while on the root folder.
+
+### 3) The Wallet Service container
+This is the actual serverless application containing the externally consumed API. Its Dockerfile is located at `./packages/wallet-service` and is used to build the wallet service image. It needs a healthy Daemon to run correctly.
+
+Its image can be build using the `make build-service` while on the root folder.

db/Dockerfile.dev

@@ -0,0 +1,66 @@
+# Copyright 2025 Hathor Labs
+# This software is provided ‘as-is’, without any express or implied
+# warranty. In no event will the authors be held liable for any damages
+# arising from the use of this software.
+# This software cannot be redistributed unless explicitly agreed in writing with the authors.
+
+# =========================================================================
+# This Dockerfile is intended for migrating the database of a dockerized private blockchain
+# for the Wallet Service Daemon.
+#
+# It serves only as a means to run the migration scripts in an isolated environment. The container will run only
+# for as long as the migration is running, and then it will exit.
+#
+# The migration scripts do not cause any impact if it is ran multiple times, so it is safe to run this container
+# for each deployment of the Wallet Service Daemon.
+#
+# The expected image size is about 250MB as of v1.9.0
+#
+# Sample usage in a docker-compose.yml:
+#  ws-migrator:
+#    image: hathornetwork/hathor-wallet-service-migrator
+#    restart: "no"  # Critical: don't restart migration service
+#    depends_on:
+#      mysql: # Replace with your actual mysql service name
+#        condition: service_healthy
+#    environment:
+#      DB_ENDPOINT: "mysql"
+#      DB_NAME: "wallet_service"
+#      DB_USER: "wallet_service_user"
+#      DB_PASS: "password"
+#      DB_PORT: 3306
+#    networks:
+#      - hathor-privnet
+
+# This Dockerfile is used to build and run the database migration container.
+FROM node:22-alpine
+
+WORKDIR /app
+
+# Copy only the necessary files for the migration
+COPY ./db ./db
+COPY ./db/migrations ./migrations
+
+# This will install only the exact versions of sequelize, sequelize-cli and mysql2
+# that are already in use in the project, avoiding any unwanted upgrades.
+# It will also install the dotenv package, but it's not as critical and we can use the latest version.
+#
+# Note that this migrator container does not need to have all the dependencies of the main project,
+# as it will only be used to run the migration scripts. For this, a new package.json is created
+# with only the necessary dependencies, reducing image size.
+
+ARG SEQUELIZE_VERSION
+ARG SEQUELIZE_CLI_VERSION
+ARG MYSQL2_VERSION
+RUN test -n "$SEQUELIZE_VERSION" \
+  && test -n "$SEQUELIZE_CLI_VERSION" \
+  || (echo "Both SEQUELIZE_VERSION and SEQUELIZE_CLI_VERSION must be set" && exit 1)
+# Avoids potential conflicts with pre-installed v1.x versions of yarn
+RUN npm uninstall -g yarn
+RUN corepack enable
+RUN echo '{"name": "migrator", "private": true}' > package.json
+RUN yarn add sequelize@"$SEQUELIZE_VERSION" sequelize-cli@"$SEQUELIZE_CLI_VERSION" mysql2@"$MYSQL2_VERSION" dotenv
+
+# Run the migration scripts
+RUN cp /app/db/migration-entrypoint.sh /app;
+ENTRYPOINT ["/bin/sh", "/app/migration-entrypoint.sh"]

db/config.js

@@ -5,7 +5,7 @@ module.exports = {
     username: process.env.DB_USER,
     password: process.env.DB_PASS,
     database: process.env.DB_NAME,
-    host: '127.0.0.1',
+    host: process.env.DB_ENDPOINT || '127.0.0.1',
     port: process.env.DB_PORT || 3306,
     dialect: 'mysql',
     dialectOptions: {

db/migration-entrypoint.sh

@@ -0,0 +1,10 @@
+#!/bin/sh
+set -e
+
+# Run the migration script.
+# Note that this is supposed to run from the root of the repository, inside a container
+corepack enable
+yarn sequelize db:migrate --config db/config.js
+
+# Run the command passed to the entrypoint (if any).
+exec "$@"

packages/daemon/Dockerfile

@@ -0,0 +1,83 @@
+# Copyright 2024 Hathor Labs
+# This software is provided ‘as-is’, without any express or implied
+# warranty. In no event will the authors be held liable for any damages
+# arising from the use of this software.
+# This software cannot be redistributed unless explicitly agreed in writing with the authors.
+
+# =========================================================================
+# This Dockerfile is used to build and run the Wallet Service Daemon container.
+# It requires:
+# - A MySQL instance, properly migrated ( see /db/Dockerfile )
+# - A Fullnode instance
+# - A Redis instance
+#
+# The expected image size is about 500MB as of v1.9.0
+#
+# See the HathorNetwork / Wallet Lib repository for a live example on how to use this Dockerfile, but in short:
+#  ws-daemon:
+#    image: hathornetwork/hathor-wallet-service-sync-daemon
+#    depends_on:
+#      ws-migrator:
+#        condition: service_completed_successfully
+#      fullnode:
+#        condition: service_healthy
+#      mysql:
+#        condition: service_healthy
+#    environment:
+#      ...
+#    ports:
+#      - "8081:8081"
+#      - "8082:8082"
+#    networks:
+#      - hathor-privnet
+
+# Build phase
+FROM node:22-alpine AS builder
+
+WORKDIR /app
+
+RUN apk update && apk add python3 g++ make py3-setuptools
+
+COPY . .
+
+# corepack will use the version of yarn specified in package.json
+RUN corepack enable
+
+# This will install dependencies for all packages, except for the lambdas since
+# they are ignored in .dockerignore
+RUN yarn install
+
+RUN yarn workspace sync-daemon run build
+
+# This will remove all dev dependencies and install production deps only
+RUN yarn workspaces focus -A --production
+
+# Run phase
+FROM node:22-alpine AS dev
+
+WORKDIR /app
+
+# Copy only the necessary files from the build phase
+COPY --from=builder /app .
+
+WORKDIR /app/packages/daemon/
+
+# The script should already be available from the builder stage copy
+RUN cp /app/scripts/fetch-fullnode-ids.js ./fetch-fullnode-ids.js
+RUN cp /app/scripts/merge-complementary-envs.sh ./merge-complementary-envs.sh
+RUN chmod +x ./merge-complementary-envs.sh
+
+# The daemon could need complementary environment variables dynamically.
+# The entrypoint script manages this before actually running the daemon.
+ENTRYPOINT ["./merge-complementary-envs.sh"]
+
+FROM node:22-alpine AS prod
+
+WORKDIR /app
+
+# Copy only the necessary files from the build phase
+COPY --from=builder /app .
+
+WORKDIR /app/packages/daemon/
+
+CMD ["node", "dist/index.js"]

packages/wallet-service/.dockerignore

@@ -0,0 +1,11 @@
+dist/
+__tests__/
+.git/
+../../.github/
+.direnv/
+flake.*
+node_modules/
+packages/daemon
+packages/wallet-service/dist/
+packages/wallet-service/node_modules/
+packages/common/node_modules/

packages/wallet-service/.nvmrc

@@ -0,0 +1 @@
+22

packages/wallet-service/Dockerfile.dev

@@ -0,0 +1,72 @@
+# Copyright 2025 Hathor Labs
+# This software is provided 'as-is', without any express or implied
+# warranty. In no event will the authors be held liable for any damages
+# arising from the use of this software.
+# This software cannot be redistributed unless explicitly agreed in writing with the authors.
+
+# =========================================================================
+# This Dockerfile is used to build and run the Wallet Service container.
+# It requires:
+# - A MySQL instance, properly migrated ( see /db/Dockerfile )
+# - A Fullnode instance
+# - A started Wallet Service Daemon instance ( see /packages/daemon/Dockerfile )
+#
+# The expected image size is about 1800MB as of v1.9.0. This is because `serverless` is a development
+# dependency and needs to be installed in the final image, reducing the optimization options for
+# reducing this size.
+#
+# To properly connect to a dockerized private network, in the environment variables, you should set `MOCK_AWS=true`
+# to avoid trying to connect to external AWS services, except if the container is being run connected to a publicly
+# available network.
+#
+# See the HathorNetwork / Wallet Lib repository for a live example on how to use this Dockerfile, but in short:
+#  ws-serverless:
+#    image: hathornetwork/hathor-wallet-service-service
+#    depends_on:
+#      fullnode:
+#        condition: service_healthy
+#      mysql:
+#        condition: service_healthy
+#      ws-daemon:
+#        condition: service_started
+#    environment:
+#      IS_OFFLINE: true
+#      ENV MOCK_AWS=true # Necessary to avoid trying to connect to external AWS services
+#      ...
+#    ports:
+#      - "3000:3000"
+#      - "3001:3001"
+#    networks:
+#      - hathor-privnet
+
+# Build stage
+FROM node:22-alpine
+
+# Install system dependencies needed for native modules
+RUN apk add --no-cache \
+    python3 \
+    g++ \
+    make \
+    py3-setuptools \
+    git
+
+WORKDIR /app
+
+# Copy root package files
+COPY . .
+
+# Enable corepack for yarn
+RUN corepack enable
+RUN yarn install
+
+WORKDIR /app/packages/wallet-service
+
+# Expose serverless-offline default port
+EXPOSE 3000
+# Expose websocket port
+EXPOSE 3001
+
+RUN chmod +x ./entrypoint.sh
+
+# Run serverless offline
+ENTRYPOINT ["./entrypoint.sh"]

packages/wallet-service/README.md

@@ -31,7 +31,7 @@ database to get the information.
 The plugin `serverless-offline` is used to emulate AWS Lambda and API Gateway on a local machine.
 
 ### Requirements
-1. NodeJS v16
+1. NodeJS v22
 
 ### Local database
 To setup a local database, you will need:

packages/wallet-service/entrypoint.sh

@@ -0,0 +1,10 @@
+#!/bin/sh
+
+set -e
+
+# When MOCK_AWS is set to true, copy the mocked AWS credentials fixtures to .aws in the working directory
+if [ "$MOCK_AWS" = "true" ]; then
+  cp -r tests/fixtures/aws ./.aws
+fi
+
+yarn serverless offline start --host 0.0.0.0 --httpPort 3000

packages/wallet-service/package.json

@@ -6,7 +6,11 @@
     "lint": "eslint src/ tests/ --ext .js,.jsx,.ts,.tsx src tests",
     "lint-fix": "eslint src/ tests/ --fix --ext .js,.jsx,.ts,.tsx src tests",
     "check-types": "tsc --noemit --skipLibCheck",
-    "test": "jest"
+    "test": "jest",
+    "debug:offline": "node --inspect-brk ./node_modules/.bin/serverless offline start --host 0.0.0.0 --httpPort 3000"
+  },
+  "engines": {
+    "node": "22"
   },
   "author": "Hathor Labs",
   "license": "MIT",
@@ -64,7 +68,7 @@
     "serverless-api-gateway-throttling": "2.0.3",
     "serverless-better-credentials": "2.0.0",
     "serverless-iam-roles-per-function": "3.2.0",
-    "serverless-offline": "13.1.2",
+    "serverless-offline": "14.4.0",
     "serverless-plugin-aws-alerts": "1.7.5",
     "serverless-plugin-monorepo": "0.11.0",
     "serverless-plugin-warmup": "8.2.1",