NPRPC docs

NPRPC Development Docker Image

A development image with NPRPC's C++ library, Swift package and tools pre-built, so a Swift or C++ project can build against NPRPC without building it first. Use it for building; run applications on the runtime image.

What's Included

  • Swift 6.4.1 toolchain (the image is based on swift:6.4.1)
  • NPRPC C++ library (libnprpc.so), headers and CMake config
  • npidl (IDL compiler) and npnameserver
  • Swift package nprpc_swift, pre-built: the NPRPC library, and NPRPCWeb for server-rendered pages
  • swift-mustache, which NPRPCWeb depends on
  • Boost 1.89.0
  • CMake, Ninja, pkg-config, Node.js, liburing, ffmpeg, and GPAC 26.07.0 (MP4Box and gpac) for media examples

Quick Start

Build the Image

just build-dev-image

This first builds the shared nprpc-gpac:26.07.0 artifact image, then copies its /opt/gpac tree into the development image. Docker caches the GPAC build independently of NPRPC. To build only the media tools:

just build-gpac-image

GPAC is built from a release archive verified by SHA-256 in Dockerfile.gpac, since Ubuntu no longer packages it. The headless tools embed libgpac and its modules; their system dependencies are OpenSSL (libssl3t64) and zlib (zlib1g) on Ubuntu 26.04. FFmpeg remains a separate package for transcoding.

The sibling nscalc repository's docker/Dockerfile.prod copies the same artifacts, using ARG GPAC_IMAGE=nprpc-gpac:26.07.0, and installs those two runtime dependencies. Its deploy script ships this image to the server when needed, alongside nprpc-runtime. Override with --gpac-image <image:tag>. The GPAC image contains artifacts only; use COPY --from, rather than running it as a container. For direct docker build -f Dockerfile.dev ., build the GPAC image first (or pass --build-arg GPAC_IMAGE=<image:tag>).

This creates nprpc-dev:latest with everything under /opt/:

  • /opt/nprpc: C++ library, headers, tools, CMake config
  • /opt/nprpc_swift: Swift package (source + compiled)
  • /opt/swift-mustache: template engine used by NPRPCWeb
  • /opt/boost: Boost libraries
  • /opt/gpac: shared media tools and resources

The image runs as the ubuntu user (UID/GID 1000). Pass --user $(id -u):$(id -g) so files written to a mounted directory belong to you.

Use in Your Project

1. As Base Image (Dockerfile)

FROM nprpc-dev:latest

WORKDIR /app
COPY Package.swift .
COPY Sources ./Sources

# Swift projects can reference NPRPC package
RUN swift build -c release

2. Mount Project Directory

# Build your Swift project
docker run --rm --user $(id -u):$(id -g) \
  -v $(pwd):/project \
  -w /project \
  nprpc-dev:latest \
  swift build

# Run tests
docker run --rm \
  -v $(pwd):/project \
  -w /project \
  nprpc-dev:latest \
  swift test

3. Interactive Development

docker run -it --rm \
  -v $(pwd):/project \
  -w /project \
  nprpc-dev:latest \
  /bin/bash

# Inside container:
npidl --version          # IDL compiler available
npnameserver &           # Start nameserver
swift build              # Build your project

Using NPRPC in Your Swift Package

Package.swift

// swift-tools-version: 6.0
import PackageDescription

let package = Package(
    name: "MyRpcService",
    dependencies: [
        // Reference installed NPRPC Swift package
        .package(path: "/opt/nprpc_swift")
    ],
    targets: [
        .executableTarget(
            name: "MyRpcService",
            dependencies: [
                .product(name: "NPRPC", package: "nprpc_swift"),
                // Only if you render pages with Mustache templates:
                .product(name: "NPRPCWeb", package: "nprpc_swift"),
            ],
            swiftSettings: [.interoperabilityMode(.Cxx)]
        )
    ]
)

Targets that import NPRPC need C++ interoperability enabled, as above.

Using NPRPC in CMake Projects

The image includes CMake config files for easy integration:

cmake_minimum_required(VERSION 3.15)
project(my_rpc_client)

# Include NPRPC toolchain hints
include(/opt/nprpc-toolchain.cmake)

# Find NPRPC
find_package(nprpc REQUIRED)

add_executable(client client.cpp)
target_link_libraries(client PRIVATE nprpc::nprpc)

Build:

docker run --rm -v $(pwd):/project -w /project nprpc-dev:latest \
  bash -c "cmake -B build && cmake --build build"

Environment Variables

Pre-configured in the image:

  • BOOST_ROOT=/opt/boost
  • NPRPC_ROOT=/opt/nprpc
  • NPRPC_SWIFT_ROOT=/opt/nprpc_swift
  • PATH includes /opt/nprpc/bin (npidl, npnameserver)
  • PATH includes /opt/gpac/bin (MP4Box, gpac)
  • LD_LIBRARY_PATH includes /opt/nprpc/lib and /opt/boost/lib
  • PKG_CONFIG_PATH includes /opt/nprpc/lib/pkgconfig

Customization

Build with Different Tag

just build-dev-image mycompany/nprpc 1.0.0

Push to Registry

docker tag nprpc-dev:latest myregistry.com/nprpc-dev:latest
docker push myregistry.com/nprpc-dev:latest

Example: Production Image

Build in this image, and run on the NPRPC runtime image, which holds only the libraries and is shared by every application on a host. See DOCKER_RUNTIME_IMAGE.md.

FROM nprpc-dev:latest AS builder
WORKDIR /app
COPY . .
RUN swift build -c release

FROM nprpc-runtime:1.0.0-<revision>
COPY --from=builder /app/.build/release/MyApp /app/MyApp
CMD ["/app/MyApp"]

Troubleshooting

Swift Can't Find NPRPC Package

Ensure your Package.swift references the correct path:

.package(path: "/opt/nprpc_swift")

CMake Can't Find nprpc

Include the toolchain file:

cmake -DCMAKE_TOOLCHAIN_FILE=/opt/nprpc-toolchain.cmake -B build

Library Not Found at Runtime

Libraries are in LD_LIBRARY_PATH, but if running executables outside the image, copy libs or mount them.

Version Information

Run inside the container:

swift --version        # Swift 6.4.1
npidl --version        # NPRPC IDL compiler
cmake --version        # CMake

docs/DOCKER_DEV_IMAGE.md