Openproject-Nextcloud Integration Helm Chart

• Dependencies
• Deploy Setup Locally (k3d)
• Configuring the Deployment
• PullPreview
• Serve From Git Branch
• Serve OpenProject From Local Branch
• Serve Standalone OpenProject (Local Branch)
• Trust Self-Signed Certificates

Dependencies

• k3d
• docker
• helm
• helm-diff plugin
• helmfile
• kubectl
• make

Deploy Setup Locally (k3d)

1. Setup Kubernetes cluster and necessary resources:

   make setup

2. Deploy the integration chart:

   make deploy

3. Check the pods:

   kubectl get pods -n opnc-integration

4. Add these hosts to your /etc/hosts file:

    sudo echo "127.0.0.1	openproject.test nextcloud.test keycloak.test openproject-assets.test" | sudo tee -a /etc/hosts

NOTE: make sure at least one setup-job-* pod is completed successfully before proceeding.

NAME                                          READY   STATUS      RESTARTS   AGE
setup-job-5nwlm                               0/1     Error       0          17m
setup-job-mkgrf                               0/1     Completed   0          12m

Access the services via the following URLs:

• OpenProject: https://openproject.test
• Nextcloud: https://nextcloud.test
• Keycloak: https://keycloak.test

To uninstall the deployment, run:

make teardown

or if you want to delete the K8s cluster as well, run:

make teardown-all

Configuring the Deployment

⚠️ Do not edit charts/opnc-integration/values.yaml directly. All configuration changes must go into environments/override/config.yaml, which will override the default values for all environments. Also, the changes in this file will not be seen by git, so it is convenient and safe to use it for changing any configuration.

Usage:

Copy the config.yaml.example to environments/override/config.yaml and add the configs as needed.

# Example: environments/override/config.yaml
integration:
  setupMethod: 'sso-external'

nextcloud:
  extraApps:
    - name: integration_openproject
      version: '2.8.1'

openproject:
  version: '17'

PullPreview

Phase 1 smoke deployment

Use the installed PullPreview CLI against the existing OpenProject chart and pullpreview/openproject-smoke-values.yaml:

PULLPREVIEW_PROVIDER=hetzner \
PULLPREVIEW_MAX_DOMAIN_LENGTH=40 \
HCLOUD_TOKEN=... \
HETZNER_CA_KEY=... \
pullpreview up /Users/crohr/dev/opf/integration-qa-helmfile \
  --name opf-op-smoke \
  --deployment-target helm \
  --chart ./charts/openproject \
  --chart-values pullpreview/openproject-smoke-values.yaml \
  --chart-set openproject.host={{ pullpreview_public_dns }} \
  --proxy-tls openproject:8080 \
  --region fsn1 \
  --image ubuntu-24.04 \
  --instance-type cpx42 \
  --dns my.preview.run

Destroy the smoke deployment with:

PULLPREVIEW_PROVIDER=hetzner pullpreview down --name opf-op-smoke

Phase 2 stack deployment

charts/pullpreview-stack packages the full OpenProject, Nextcloud, Keycloak, and integration setup as a single Helm release for PullPreview. It runs the integration chart in previewMode, which keeps the existing local k3d workflow unchanged while disabling the self-signed internal TLS path used by the README flow.

The GitHub workflow is in pullpreview.yml and expects repository secrets HCLOUD_TOKEN and HETZNER_CA_KEY, plus the trigger label pullpreview. It publishes the main OpenProject preview on the generated FQDN and exposes the related services on subdomains of that same host, for example https://<fqdn>, https://nextcloud.<fqdn>, and https://keycloak.<fqdn>/realms/opnc.

Serve From Git Branch

You can serve the OpenProject and Nextcloud servers using a specific git branch. Set the following config in the config.yaml file:

openproject:
  gitSourceBranch: '<git-branch-name>'

nextcloud:
  gitSourceBranch: '<git-branch-name>'

Similarly, you can enable Nextcloud apps using a specific git branch:

nextcloud:
  enableApps:
    - name: 'app_name'
      gitBranch: '<app-git-branch>'

NOTE: This can take a long time to build the source code and deploy the application.

Serve OpenProject From Local Branch

You can serve the OpenProject using the local source path. Run the following command:

1. Teardown existing deployment (if any):

   make teardown-all

2. Setup the cluster again with local source path:

   OP_LOCAL_REPO_DIR=<path-to-local-openproject-repo> make setup

3. Deploy the dev setup:

   make deploy-dev

NOTE: This can take a long time to build the source code and deploy the application.

Serve Standalone OpenProject (Local Branch)

You can serve the OpenProject in standalone mode for the development setup. This doesn't run Nextcloud and Keycloak. Run the following command:

1. Teardown existing deployment (if any):

   make teardown-all

2. Setup the cluster again with local source path:

   OP_LOCAL_REPO_DIR=<path-to-local-openproject-repo> make setup

3. Deploy the dev setup:

   make deploy-op-standalone

Trust Self-Signed Certificates

If you are using self-signed certificates, you may need to trust them in your browser. Follow these steps:

1. Get the certificate from the cluster:

   kubectl get secret opnc-ca-secret -n opnc-integration -o jsonpath='{.data.ca\.crt}' | base64 -d > opnc-root-ca.crt

2. Import the certificate:

   a. Linux

   sudo cp opnc-root-ca.crt /usr/local/share/ca-certificates/
   sudo update-ca-certificates

   Import the certificate into the certificates store (for browsers):

   certutil -A -n "NC-OP Integration Root CA" -t TC -d sql:"$HOME/.pki/nssdb" -i opnc-root-ca.crt

   b. macOS

   sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain opnc-root-ca.crt

Running RSpec Tests

You can run the RSpec tests when running the setup in development mode.

1. Run the setup in development mode:

   make deploy-dev
   # or
   make deploy-op-standalone

   Or, make sure the following configs are set:

   # environments/default/config.yaml
   railsEnv: 'development'
   enableTestSetup: true

2. Run the tests:

   make run-rspec-test SPEC=spec/features/auth/login_spec.rb