Use this guide to deploy BoldDocServer and configure HTTPS access for SharePoint and user’s browsers. Complete [Deployment Prerequisites](./deployment-prerequisites) before starting.

## 1. Prepare the deployment files

Follow [Quick Start steps 1–3](../quick-start#1-create-the-deployment-folder) to create `docker-compose.yaml`, enter your settings, and add the certificate and dictionary files.

Use your BoldDocServer hostname in place of `bolddocserver.example.com` throughout this guide. Keep `WOPI_HOST_URL` set to the HTTPS address that SharePoint and user’s browsers will access.

## 2. Configure HTTPS access

Choose one of the following options based on your deployment environment:

- **NGINX:** Use NGINX to provide HTTPS access on Linux, macOS, or Windows.
- **IIS URL Rewrite:** Use IIS to provide HTTPS access on Windows deployments with WSL 2.

Both options provide the external HTTPS endpoint for BoldDocServer running in a Linux container.

### Configure the application port

Configure the port mapping in `docker-compose.yaml` so the HTTPS endpoint can reach BoldDocServer without exposing the application port directly to external clients.

For example, if the HTTPS endpoint connects to the application on local port `8443`, use:

```yaml
ports:
    - "127.0.0.1:8443:443"
```

This maps port `8443` on the container host to port `443` in the container and binds the host port to the loopback interface. Use this mapping when the HTTPS endpoint runs on the same host and can reach the published port through the configured Docker networking environment.

Keep the application’s certificate mounts and HTTPS settings configured as described in Quick Start.

### Configure NGINX HTTPS access

Use NGINX to provide the external HTTPS endpoint and forward requests to BoldDocServer.

1. Install NGINX on the host.
2. Configure a server block for your BoldDocServer hostname:

```nginx
events {
    worker_connections 1024;
}

http {
    server {
        listen 443 ssl;
        server_name bolddocserver.example.com;

        ssl_certificate     /path/to/certificate.crt;
        ssl_certificate_key /path/to/private-key.key;

        location / {
            proxy_pass https://127.0.0.1:8443;

            proxy_http_version 1.1;

            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_set_header X-Forwarded-Host $http_host;
            proxy_set_header X-Forwarded-Port 443;

            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "upgrade";

            proxy_read_timeout 300s;
            proxy_send_timeout 300s;
        }
    }
}
```

**Note:** The location of the NGINX configuration depends on the installation. For standalone installations on Windows and macOS, add the `server` block inside the `http {}` section of the main `nginx.conf` file. On Linux, you can either add the `server` block inside the existing `http {}` section of `/etc/nginx/nginx.conf` or create a separate site configuration under `/etc/nginx/sites-available/` and enable it through `/etc/nginx/sites-enabled/`. When using a separate site configuration, include only the `server` block; do not add separate `events {}` or `http {}` sections.

3. Replace the following values with your deployment details:
   - `server_name`: The hostname configured for BoldDocServer.
   - `ssl_certificate`: The path to your trusted TLS certificate on the host.
   - `ssl_certificate_key`: The path to the corresponding private key.
   - `proxy_pass`: The BoldDocServer application endpoint published on the host.
4. Ensure the hostname resolves to the host running NGINX and that inbound HTTPS traffic is allowed on port `443`.
5. Validate the NGINX configuration and reload NGINX to apply the changes. NGINX must already be running before you reload it. If it is not running, start it first.

**Linux:**

```bash
sudo nginx -t
sudo systemctl reload nginx
```

**macOS:**

```bash
sudo nginx -t
sudo nginx -s reload
```

**Windows PowerShell** (run from the NGINX installation directory):

```powershell
.\nginx.exe -t
.\nginx.exe -s reload
```
**Expected result:** NGINX configuration validation succeeds, and the BoldDocServer hostname is accessible over HTTPS on port `443`. Requests are forwarded to the application on port `8443`.

### Configure IIS HTTPS Access

For Windows deployments using WSL 2, you can alternatively configure IIS to provide HTTPS access to BoldDocServer.

1. Install the **IIS URL Rewrite** module.
2. Open **IIS Manager** and create or select the website that will provide access to BoldDocServer.
3. Add an **HTTPS binding**:
   - Type: `https`
   - Port: `443`
   - Host name: `bolddocserver.example.com`
   - SSL/TLS certificate: Select a trusted certificate for the hostname.
4. Configure the **URL Rewrite** rule:
   - Pattern: `(.*)`
   - Action: `Rewrite`
   - Rewrite URL: `https://127.0.0.1:8443/{R:1}`
   - Enable **Append query string**.
5. Install **Application Request Routing (ARR)** if it is not already installed, and enable **Proxy** in its server-level settings.
6. Configure the Windows Firewall to allow inbound HTTPS traffic on port 443.

   **Note:** BoldDocServer uses SignalR over WebSockets for real-time collaborative editing. Ensure the **WebSocket Protocol** feature is installed and enabled in IIS on the Windows host. 

If IIS connects to the application over HTTPS, ensure that the application endpoint is reachable and its TLS certificate is trusted and valid for the hostname IIS uses to connect.

## 3. Start the service

From the folder containing `docker-compose.yaml`, run:

```bash
docker compose up -d
docker compose ps
```

**Expected result:** The `app` service is running. 

If it fails to start, see [Container fails to start](../troubleshooting/troubleshooting-reference#container-fails-to-start).

## 4. Verify HTTPS access

After the container starts, test the configured HTTPS endpoint to verify that requests reach BoldDocServer.

### NGINX

1. Test the endpoint locally on the machine hosting NGINX.

**Linux/macOS:**

```bash
curl -vk --resolve bolddocserver.example.com:443:127.0.0.1 "https://bolddocserver.example.com/hosting/discovery"
```

**Windows PowerShell:**

```powershell
curl.exe -vk --resolve bolddocserver.example.com:443:127.0.0.1 "https://bolddocserver.example.com/hosting/discovery"
```

2. Test the public URL from an external machine.

**Linux/macOS:**

```bash
curl -v "https://bolddocserver.example.com/hosting/discovery"
```

**Windows PowerShell:**

```powershell
curl.exe -v "https://bolddocserver.example.com/hosting/discovery"
```

**Expected result:** Both tests return `HTTP 200 OK` with WOPI discovery XML.

**Note:** The local test uses `-k` to skip TLS certificate validation for diagnostic purposes. The external test verifies the public endpoint using normal TLS certificate validation.

### IIS URL Rewrite

1. Test the endpoint locally on the Windows host:

```powershell
curl.exe -vk --resolve bolddocserver.example.com:443:127.0.0.1 "https://bolddocserver.example.com/hosting/discovery"
```

2. Test the public URL from an external machine:

```powershell
curl.exe -v "https://bolddocserver.example.com/hosting/discovery"
```

**Expected result:** Both tests return `HTTP 200 OK` with WOPI discovery XML.

**Note:** The local test uses `-k` to skip TLS certificate validation for diagnostic purposes. The external test verifies the public endpoint using normal TLS certificate validation.

### Verify the configuration

Confirm that:

- The BoldDocServer hostname resolves correctly from SharePoint Server and user's browsers.
- NGINX or IIS serves the configured hostname over trusted HTTPS.
- The configured HTTPS endpoint routes requests to the application.
- The application endpoint is not unnecessarily exposed to external clients.
- `WOPI_HOST_URL` matches the HTTPS address used by SharePoint and users.

See [Deployment Prerequisites](./deployment-prerequisites) for the network and firewall requirements.

## 5. Connect SharePoint

From the SharePoint server, request the public discovery endpoint:

```powershell
curl.exe -i https://bolddocserver.example.com/hosting/discovery
```

**Expected result:** The request succeeds over trusted HTTPS and returns discovery XML containing editor URLs that use the public BoldDocServer hostname.

Ensure user’s browsers can also reach this address and trust its TLS certificate. If discovery fails, see [Discovery troubleshooting](../troubleshooting/troubleshooting-reference#wopi-discovery-endpoint-returns-an-error). For NGINX or IIS URL Rewrite errors, see [NGINX or IIS URL Rewrite returns 404 or 500](../troubleshooting/troubleshooting-reference#nginx-or-iis-url-rewrite-returns-404-or-500).

Next, follow [Connect SharePoint](../integrations/sharepoint-integration) to register the WOPI bindings and test opening, editing, saving, and reopening a document. Reopening the document verifies that changes were saved to SharePoint.

## Lifecycle management

Run these commands from the deployment folder when you need the corresponding action.

| Action | Command |
|---|---|
| Check service status | `docker compose ps` |
| View recent application logs | `docker compose logs --tail 200 app` |
| Stop services | `docker compose stop` |
| Start stopped services | `docker compose start` |
| Restart the application | `docker compose restart app` |

### Update BoldDocServer

1. Save a copy of the current `docker-compose.yaml` and record the current Docker image name.
2. Review the new version’s release notes and update the `image` value to the intended version.
3. Pull the image and apply the updated configuration:

```bash
docker compose pull
docker compose up -d
```

4. Repeat the discovery check and open, edit, save, and reopen a test document from SharePoint.

### Remove the containers

To stop and remove the deployment’s containers and Compose-managed network, run:

```bash
docker compose down
```

Host-mounted certificate and dictionary files remain in the deployment folder. Documents remain in SharePoint.