mait.sh1.132.1

Private beta: features and content may change. No warranty; use at your own risk.

Install AIDC Server

Plan an on-premise AIDC Server that replaces the MAIT Hub: receive the server's files, deploy it as a container or with the Helm chart, check that it answers, and record its signing-key fingerprint.

Beta
OverviewInstallWorkflowsOperateCustomizeInsideProblems and fixesAll components
Prerequisites

What an on-premise AIDC Server needs from you.

You provideWhy
A Linux amd64 host with a container runtime, or a Kubernetes cluster with Helm 3 and a default storage classThe server ships as a container image and a Helm chart
One persistent volume for /var/lib/aidc/hub, writable by user ID 1000Packages, the package database and the signing keys all live there
A DNS name and an address your people and pipelines can reach over HTTPSClients keep one server address and one trust file
Outbound access to upstream vendors (optional)Only version discovery and vendor-key refresh use it; stored packages are served without it
A decision between direct HTTPS and gateway modeThe customize page compares them
Steps

Six steps from the supplied files to an AIDC Server that answers.

Deploying the server, proving that clients can reach it and proving that protected requests are accepted are separate steps, and success at one does not prove the next. Check each result before moving on. The details for each deployment mode are in serve HTTPS directly and deploy behind a gateway.

  1. Step 1 of 6

    Receive your files

    The MAIT Team supplies three kinds of file with your on-premise setup. The server's HTTPS bundle identifies your AIDC Server to its clients; you install it on the server, or on the gateway in gateway mode. The trust file lets clients recognise your AIDC Server. Credential files, each with its own private key, identify one user or pipeline and carry that holder's features. You also receive the access-check setting, the address the server uses to confirm accounts and credentials on each protected request.

    You need a Linux amd64 host with a container runtime, or a Kubernetes cluster with Helm 3 and a default storage class, plus a persistent volume for /var/lib/aidc/hub that user ID 1000 can write to. Run exactly one instance per volume: the package database accepts one writer.

    What you get

    The bundle, the trust file, one credential file per holder and the access-check setting, from a source you can name.

  2. Deploy with the Helm chart
    $ kubectl create namespace aidc
    $ kubectl -n aidc create secret generic aidc-server-tls --from-file=tls.crt=hub-bundle.pem
    $ helm install aidc-server ./aidc-server-chart -n aidc -f aidc-values.yaml
    $ kubectl -n aidc rollout status deployment/aidc-server
    aidc-values.yaml
    image:
  tag: "<version>"
persistence:
  size: 20Gi
liveAccess:
  url: "<access-check address from your on-premise setup>"
    Deploy as a container
    $ docker run -d --name aidc-server -p 8443:8443 \
    $ -v /srv/aidc/data:/var/lib/aidc/hub \
    $ -v /srv/aidc/tls:/etc/aidc/hub/tls:ro \
    $ -e AIDC_HUB_PORT=8443 \
    $ -e AIDC_HUB_CERT_BUNDLE=/etc/aidc/hub/tls/tls.crt \
    $ --env-file /srv/aidc/access.env \
    $ --no-healthcheck \
    $ ghcr.io/mait-sh/aidc-server:<version>
    Step 2 of 6

    Deploy the server

    On Kubernetes, store the bundle in the secret the chart mounts, write the values you change, and install.

    Keep replicaCount: 1 and the default Recreate rollout strategy. As a container, put the bundle at /srv/aidc/tls/tls.crt, the data directory at /srv/aidc/data, both owned by user ID 1000, and start the server with the port and bundle set explicitly:

    The bundle contains the server's private key; keep it readable only by the account that runs the server. When a gateway already fronts your cluster, use gateway mode instead: the server then listens on port 8080 for the gateway, and the gateway must be the only way to reach the server.

    What you get

    One running server and one data volume.

  3. Illustrative
    The start of the log
    aidc-server starting...
  Storage path: /var/lib/aidc/hub/packages
  Database: /var/lib/aidc/hub/index.db?mode=rwc
  Bind address: 0.0.0.0:8080
Configuration loaded
  Gateway mode: true
KeyStore initialized successfully
Filesystem scan: 0 on disk, 0 already in DB, 0 newly indexed
Hub public key fingerprint: 0123456789abcdef
Auto re-signing configuration:
  Enabled: true
  Interval: 86400 seconds (24 hours)
Version refresh configuration:
  Enabled: false
  Interval: 10800 seconds (3 hours)
Consistency check configuration:
  Enabled: true
  Interval: 43200 seconds (12 hours)
Metrics endpoint listening on 0.0.0.0:9090
Starting server on 0.0.0.0:8080
    Step 3 of 6

    Read the startup log

    On a first start the server creates its signing key, scans the volume for packages and starts its scheduled jobs.

    Direct mode ends with Starting server on 0.0.0.0:8443 and fails at startup with TLS certificate bundle not found if the bundle is missing.

    What you get

    The bind port, the storage path, the scheduled jobs and the server's signing-key fingerprint.

  4. Check health
    $ curl --fail --cacert server-trust.pem https://hub.example.com:8443/health
    Illustrative
    What it prints
    $ curl -s http://localhost:18080/health
    {"status":"ok","version":"3.21.6","commit":"example-build"}
    Step 4 of 6

    Check health

    Health needs no credentials, so it only shows that the service answers.

    A status of ok does not test credentials, prove that a package exists, or certify that every background job succeeds.

    What you get

    A response with status, version and commit.

  5. Authenticated check
    $ curl --fail --cacert server-trust.pem --cert client.pem --key client-key.pem \
    $ https://hub.example.com:8443/api/v1/packages
    Capturedaidc-server 3.21.6
    Without a credential
    $ curl -si http://localhost:18080/api/v1/packages
    HTTP/1.1 401 Unauthorized
    content-type: text/plain; charset=utf-8
     
    Credentials required
    Step 5 of 6

    Check access with a credential

    A catalogue request proves that HTTPS, the access check and the package store work together. An empty list is a valid answer on a new AIDC Server.

    A 503 on every protected request while health is green means the access-check setting is missing or wrong, or the server cannot reach its address.

    What you get

    A JSON array from the catalogue, or a status that tells you which setting to repair.

  6. Show the keys
    $ docker exec aidc-server aidc-server keys status
    Illustrative
    What it prints
    $ aidc-server keys status
     
    Key Status
     
    Active Key:
    Fingerprint: 0123456789abcdef
    Description: Initial key (auto-generated on startup)
    Packages: 0
     
    Trusted Keys: 0
    Step 6 of 6

    Record the signing-key fingerprint

    Keep the fingerprint for later restore checks. Run the administrative command in the running container, so it sees the same volume and settings.

    On Kubernetes, prefix the command with kubectl -n aidc exec deploy/aidc-server --. Give each client the server address, the trust file and its own credential files.

    What you get

    A recorded fingerprint, and an AIDC Server ready for its first publication.

Next

Where to go next.

  • Workflows, for publishing, consuming and operating