Installation prerequisites
Prepare the items on this page before scheduling an InsightSpace installation. The recommended on-premises deployment uses one application server and a separate GPU inference device. Confirm any deviation from this topology with the InsightSpace team before provisioning hardware.
Information the client must provide
Section titled “Information the client must provide”Hostnames and DNS
Section titled “Hostnames and DNS”InsightSpace requires two hostnames so the reverse proxy can route browser and API traffic independently:
| Purpose | Example |
|---|---|
| Web application | insightspace.acme.com |
| API | api.insightspace.acme.com |
The names may be public or available only through an internal network or VPN. In either case:
- both names must resolve to the InsightSpace application server, load balancer, or reverse proxy;
- every user device must be able to resolve and reach both names; and
- the InsightSpace installation team must be able to reach the environment through the agreed administration path.
For a private installation, create the records in internal DNS and confirm that they resolve while connected to the VPN. Do not use an IP address as the browser address.
HTTPS and TLS certificate
Section titled “HTTPS and TLS certificate”HTTPS is required. InsightSpace authentication uses secure cookies, which browsers transmit only over HTTPS. The certificate must be trusted by all user devices and valid for both the web application and API hostnames.
Choose one of these certificate arrangements:
| Environment | Certificate arrangement | Client action |
|---|---|---|
| Publicly reachable | Caddy obtains and renews a publicly trusted certificate automatically. | Publish both DNS records, allow public certificate validation, and permit inbound TCP 80 and 443 to Caddy. |
| Internal network or VPN | The client provides a certificate issued by its trusted public or internal certificate authority. | Supply a readable PEM certificate chain and its matching PEM private key through an agreed secure channel. Include both hostnames in the certificate’s subject alternative names. |
| Internal Caddy CA | Caddy generates an internal certificate. This is the least convenient option. | Install and trust the generated Caddy root certificate on every user device. |
If the client terminates HTTPS on an existing reverse proxy or load balancer, that component owns the certificate. It must still route the two hostnames to the corresponding InsightSpace services.
The HTTPS certificate described here is separate from the application data-protection certificate, which the installer generates and manages locally.
SMTP account
Section titled “SMTP account”InsightSpace needs an SMTP account to send onboarding messages, invitations, email confirmations, password-recovery messages, email-change confirmations, and other user notifications.
Provide:
- SMTP server hostname;
- SMTP submission port, normally
587; - SMTP username and password;
- authorized sender email address; and
- sender email domain.
The SMTP endpoint must support STARTTLS. An implicit-TLS-only endpoint on port 465 is not
supported by the standard installation. Permit outbound SMTP traffic from the application server
and allowlist its source address if the mail service requires it. The sender address must be allowed
for the supplied account.
Share the password only through the agreed secure channel. The installer stores it as a protected secret file rather than in the Compose environment.
Server access and network rules
Section titled “Server access and network rules”Provide the InsightSpace installation team with:
- administrative access to the application server through SSH or the client’s approved equivalent;
rootor passwordlesssudoaccess for the installation;- the server’s private or VPN interface address when the installation is not public; and
- the SSH port that must remain permitted when the host firewall is configured.
The application server must be able to pull InsightSpace container images from GitHub Container
Registry. Provide direct outbound internet access or, at minimum, permit outbound HTTPS to
raw.githubusercontent.com, ghcr.io, the associated GitHub package-download endpoints, and the
operating-system package repositories used during installation. Ask the InsightSpace team for a
release-specific allowlist when outbound access is restricted. A split deployment also requires
private network connectivity from the application server to the inference services on the GPU
device.
For the standard Caddy deployment, expose only the reverse proxy to users:
- TCP
443is required for InsightSpace access; - TCP
80is required when Caddy performs public certificate provisioning and renewal; and - database, object-storage, extraction, frontend, and backend container ports remain private.
If the client supplies an external database, object store, reverse proxy, or inference service, provide its endpoint, credentials, certificate trust chain, and required firewall rules before the installation.
Hardware requirements
Section titled “Hardware requirements”Recommended split deployment
Section titled “Recommended split deployment”Use two separate devices so normal application activity does not compete with AI inference.
Application server
Section titled “Application server”The application server runs the frontend, backend, PostgreSQL with pgvector, S3-compatible object storage, document extraction, reverse proxy, and supporting services.
| Resource | Baseline |
|---|---|
| Host | Dedicated virtual or physical server |
| CPU | 8 cores |
| Memory | 16 GB RAM |
| Storage | 1 TB SSD |
| Operating system | Ubuntu Server 22.04 or 24.04 LTS, 64-bit x86 or Arm |
These are the operating-system versions accepted by the current installer; confirm them again when deploying a later release. Storage must be sized for uploaded source documents, extracted artifacts, the database, vector indexes, backups, logs, and expected growth. Larger document collections or concurrent extraction workloads may require more CPU, memory, and storage.
AI inference device
Section titled “AI inference device”Provide a dedicated GPU inference device with AI compute capability and memory capacity at least equivalent to an NVIDIA DGX Spark. It runs the approved local chat, embedding, and reranking models.
The device must:
- be reachable from the application server over a stable private network;
- expose only the agreed inference endpoints to that network; and
- have enough local storage for the selected model files and future model updates.
Final GPU sizing depends on the selected models, context sizes, expected concurrency, and response time target. Confirm the model set with the InsightSpace team before purchasing alternative hardware.
Compact single-device deployment
Section titled “Compact single-device deployment”The complete stack can run on one DGX Spark-class device. This is suitable where space or infrastructure is constrained, but application, extraction, storage, and inference workloads share the same resources. It provides less performance headroom and a smaller fault-isolation boundary than the recommended two-device deployment.
Items supplied by InsightSpace
Section titled “Items supplied by InsightSpace”The InsightSpace team supplies:
- a dedicated GitHub Container Registry username and package-read credential for pulling the InsightSpace container images;
- the InsightSpace license key; and
- the release-specific installation procedure and configuration template.
The registry credential and license key are secrets. Do not send them by ordinary email or place them in tickets, source control, or shared documentation.
Pre-installation handoff checklist
Section titled “Pre-installation handoff checklist”Send the completed checklist to the InsightSpace team before the installation date.
| Item | Required confirmation |
|---|---|
| Web application hostname | Final hostname and DNS resolution tested from a user device |
| API hostname | Final hostname and DNS resolution tested from a user device |
| Access model | Public, internal network, or VPN |
| HTTPS approach | Caddy public certificate, client-provided certificate, internal Caddy CA, or external proxy |
| Client-provided TLS material | PEM chain and matching private key cover both hostnames |
| SMTP | Host, port, username, password, sender address, domain, and STARTTLS support confirmed |
| Application server | Dedicated host with 8 CPU cores, 16 GB RAM, 1 TB SSD, and a supported Ubuntu release confirmed |
| Inference device | DGX Spark-class or better; selected models and private endpoint confirmed |
| Administration | Access method, server address, SSH port, and root/sudo access confirmed |
| Firewall and egress | HTTPS, certificate validation, SMTP, registry access, and inter-host rules confirmed |
| External services | Endpoints, credentials, trust chains, and ownership supplied where applicable |
| Backups | Database and object-storage backup destination, retention, and restore owner agreed |
After the checklist is complete, use the release-specific installation procedure supplied by the InsightSpace team. Continue with configuration for the settings that map these decisions into the deployment.