diff --git a/.devcontainer/.devcontainer-image.json b/.devcontainer/.devcontainer-image.json new file mode 100644 index 0000000000..db10bb5330 --- /dev/null +++ b/.devcontainer/.devcontainer-image.json @@ -0,0 +1,5 @@ +{ + "image": "quay.io/389ds/devcontainer", + "runArgs": ["--env-file",".devcontainer/overrides.env"], + "capAdd": ["SYS_PTRACE"] +} \ No newline at end of file diff --git a/.devcontainer/Containerfile b/.devcontainer/Containerfile new file mode 100644 index 0000000000..0734c83f51 --- /dev/null +++ b/.devcontainer/Containerfile @@ -0,0 +1,17 @@ +FROM quay.io/389ds/devcontainer + +COPY ./container-entrypoint.sh /container-entrypoint.sh + +RUN dnf install -y tini + +# DEFAULTS +ENV CC=gcc \ + CXX=g++ \ + CFLAGS="-O2 -g" \ + CXXFLAGS="" \ + LDFLAGS="" \ + DS_DM_PASSWORD=password \ + DS_SUFFIX_NAME=dc=example,dc=com + +ENTRYPOINT ["/usr/bin/tini", "--", "/container-entrypoint.sh"] + diff --git a/.devcontainer/DEV_CONTAINER.md b/.devcontainer/DEV_CONTAINER.md new file mode 100644 index 0000000000..a18ab1037e --- /dev/null +++ b/.devcontainer/DEV_CONTAINER.md @@ -0,0 +1,43 @@ +# 389 Directory Server Development Container + +## What is this for? +The Development Container simplifies building and running the 389 Directory Server from anywhere including Windows, Mac, and Linux by leveraging a container. The environment is therefore already setup with the correct tools and tool versions to build and run. + +## How does it work +You need to have a local container runtime such as [Docker Desktop](https://www.docker.com/products/docker-desktop/), [Podman](https://podman.io/), or [Kubernetes](https://kubernetes.io/). [Docker Compose](https://docs.docker.com/compose/) is recommended as well to simplify commands, and avoid long repetitive command lines, but not strictly required. If you don't have Docker Compose you will need to examine the `dev.yaml` and translate to container run commands. Container run commands with Kubernetes also [requires translation](https://kubernetes.io/docs/reference/kubectl/docker-cli-to-kubectl/). + +By default, the project directory is bind mounted into the container such that changes can be made on the local workstation using your favorite IDE. Other modes of operation are possible such as editing in-container or using remote development tooling such as [VS Code](https://code.visualstudio.com/docs/remote/remote-overview) or [IntelliJ](https://www.jetbrains.com/remote-development/). + +## Get and start development container: +``` +git clone https://github.com/389ds/389-ds-base +cd 389-ds-base/.devcontainer +docker compose up +``` + +## Build and Run inside the container: +``` +docker exec -it bash dirsrv +cd 389-ds-base +./build.sh +/usr/libexec/dirsrv/dscontainer -r & +# Or run dsctl, etc. +``` + +## Configure: +You can configure the development container using environment variables. Create a [.devcontainer/overrides.env](https://docs.docker.com/compose/environment-variables/set-environment-variables/) file in the project root. + +Container Runtime Environment Variables: + +| Name | Description | Default | +|--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------| +| CC | C compiler | gcc | +| CXX | C++ compiler | g++ | +| CFLAGS | C compiler flags | "-O2 -g" | +| CXXFLAGS | C++ compiler flags | | +| LDFLAGS | Linker flags | | +| DS_BACKEND_NAME | Database backend | example | +| DS_DM_PASSWORD | Directory Manager password | password | +| DS_START_TIMEOUT | Number of seconds to start dscontainer before timeout | 60 | +| DS_STOP_TIMEOUT | Number of seconds to stop dscontainer before timeout | 60 | +| CUSTOM_CRT_URL | Optional URL to site-specific (self-signed) corporate intercepting TLS proxy CA file; sometimes necessary to allow build to download artifacts from the Internet. | | diff --git a/.devcontainer/compose.yaml b/.devcontainer/compose.yaml new file mode 100644 index 0000000000..036abe1614 --- /dev/null +++ b/.devcontainer/compose.yaml @@ -0,0 +1,17 @@ +services: + dirsrv: + build: + context: . + dockerfile: Containerfile + hostname: dirsrv + container_name: dirsrv + ports: + - "3389:3389" + - "3636:3636" + cap_add: + - SYS_PTRACE + env_file: + - path: ./overrides.env + required: false + volumes: + - ../:/389-ds-base \ No newline at end of file diff --git a/.devcontainer/container-entrypoint.sh b/.devcontainer/container-entrypoint.sh new file mode 100644 index 0000000000..92d17313cf --- /dev/null +++ b/.devcontainer/container-entrypoint.sh @@ -0,0 +1,27 @@ +#!/bin/bash + +## +# Check if a site-specific (self-signed) CA cert is set in the environment variable CUSTOM_CRT_URL, +# and if it is then update trust anchors. This is necessary for users behind a corporate TLS +# intercepting proxy as otherwise the build will fail to download artifacts from the Internet. +# +# Note: check only runs if hasn't run yet. However, if container isn't running as root then the +# location of marker files needs to be updated. +## +if [ ! -f /cert-check-complete ]; then + if [ -z "$CUSTOM_CRT_URL" ] ; then echo "No custom cert specified in CUSTOM_CRT_URL env; skipping"; else \ + curl -o /etc/pki/ca-trust/source/anchors/customcert.crt $CUSTOM_CRT_URL + update-ca-trust + fi + touch /cert-check-complete +else + echo "Cert check already complete; skipping" +fi + +echo "Container ready!" + +## +# Note: PID 1 should actually be tini or similar. If users decide to override the entrypoint +# it is recommended to continue to use tini or similar. +## +sleep infinity \ No newline at end of file diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 0000000000..e73c69e3d7 --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,5 @@ +{ + "dockerComposeFile": "compose.yaml", + "service": "dirsrv", + "workspaceFolder": "/389-ds-base" +} \ No newline at end of file diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000000..07764a78d9 --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +* text eol=lf \ No newline at end of file diff --git a/.gitignore b/.gitignore index 4c4f5f8d0e..8c333dcaf4 100644 --- a/.gitignore +++ b/.gitignore @@ -240,3 +240,4 @@ vendor.tar.gz /rust-nsslapd-private.h /rust-slapi-private.h /src/lib389/setup.py +/.devcontainer/overrides.env diff --git a/README.md b/README.md index d26633aa2e..4d5591b3e8 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,9 @@ Building Note: **--enable-asan** is optional, and it should only be used for debugging/development purposes. -See also full [building guide](https://www.port389.org/docs/389ds/development/building.html). +See also: +- Full [Building Guide](https://www.port389.org/docs/389ds/development/building.html) +- Portable [Development Container guide](https://github.com/389ds/389-ds-base/blob/main/.devcontainer/DEV_CONTAINER.md) Testing ------- diff --git a/build.sh b/build.sh new file mode 100755 index 0000000000..62d5f6681a --- /dev/null +++ b/build.sh @@ -0,0 +1,9 @@ +#!/bin/bash +set -e + +autoreconf -fiv +./configure --enable-debug --with-openldap --enable-cmocka --enable-asan +make +make lib389 +make install +make lib389-install \ No newline at end of file