Configure your Connect server - 1Password Developer

This article documents Connect server environment variables and special configuration options, such as TLS and manual bus configuration. 1Password Connect Server consists of two containers running in the same network:

The Connect API container (1password/connect-api )
The Connect sync container (1password/connect-sync )

Both containers require a shared volume to store an encrypted copy of your data.

Requirements

Before you can configure your 1Password Connect Server, you must:

Environment variables

The following table lists the available environment variables, their description, and the containers that support them. Most of the environment variables apply to the Connect API and Connect sync containers, but some only apply to the Connect API container.

Environment variable	Description	Container support
`OP_SESSION`	The path to the `1password-credentials.json` file. You can also set the value to the Base64-encoded content of the `1password-credentials.json` file. Acceptable values: A full file path to the `1password-credentials.json` file. Default value: `~/.op/1password-credentials.json`	• Connect API • Connect sync
`OP_HTTP_PORT`	The port for the HTTP server. Acceptable values: Any available port number. Default value: `8080`	• Connect API • Connect sync
`OP_LOG_LEVEL`	The logging level of the container. Acceptable values: `info`, `error`, `debug` Default value: `info`	• Connect API • Connect sync
`XDG_DATA_HOME`	The path in which to create the `.op/data/` directory. See Data volume. Acceptable values: A valid file path. Default value: `/home/opuser/.op/data`	• Connect API • Connect sync
`OP_BUS_PORT`	The port for listening to incoming bus connections from other containers. See Manual bus configuration for more details. Acceptable values: Any available port number. Default value: A random free port	• Connect API • Connect sync
`OP_BUS_PEERS`	A comma-separated list of `[hostname]:[bus port]` pairs of other containers to connect to. See Manual bus configuration for more details. Acceptable values: A comma-separated list of `[hostname]:[bus port]` pairs. Default value: No default because this variable is optional.	• Connect API • Connect sync
`OP_HTTPS_PORT`	The port for the HTTP server when using TLS. Acceptable values: Any available port number. Default value: `8443`	• Connect API
`OP_SYNC_TIMEOUT`	The time (in seconds) to wait for the initial sync to complete. Acceptable values: A time duration (for example, `1h`, `30m`, `20s`). Default value: `10s` (10 seconds)	• Connect API
`OP_TLS_KEY_FILE`	The path to the private key file. Only use this environment variable if you plan to use TLS with your own certificate. Acceptable values: A valid file path. Default value: No default because this variable is optional.	• Connect API
`OP_TLS_CERT_FILE`	The path to the certificate file. This should be the full certificate chain. Only use this environment variable if you plan to use TLS with your own certificate. Acceptable values: A valid file path. Default value: No default because this variable is optional.	• Connect API
`OP_TLS_USE_LETSENCRYPT`	Only use this environment variable if you want to use TLS with a Lets Encrypt certificate. Acceptable values: Any value (for example, `1`, `true`, or `yes`). Default value: No default because this variable is optional.	• Connect API
`OP_TLS_DOMAIN`	The (sub-)domain for which to request a certificate. The DNS records for this domain must point to the Connect server. See TLS. Acceptable values: Any domain (or subdomain) name. Default value: No default because this variable is optional.	• Connect API

Data volume

The default location of the shared volume is /home/opuser/.op/data. If you set the XDG_DATA_HOME environment variable to a path other than /home/opuser/, make sure you mount your data volume at the same path.

TLS

By default, 1Password Connect Server is configured for use within a trusted network. If you plan to use Connect outside a trusted network, consider configuring Transport Layer Security (TLS) . You can configure TLS for the connection between your application and Connect by providing your own certificate or letting Connect request a certificate using Let’s Encrypt. Connect listens on the port defined by the OP_HTTPS_PORT environment variable (default 8443) when you use TLS.

Use your own certificate

Connect can use a PEM-encoded private key and certificate by setting the following two environment variables for the Connect API container:

Set OP_TLS_KEY_FILE to the path to the private key file.
Set OP_TLS_CERT_FILE to the path to the certificate file. This should be the full certificate chain.

Use Let’s Encrypt

Connect can also request a certificate from the Let’s Encrypt Certificate Authority (CA). For this, you must set two environment variables for the Connect API container:

Set OP_TLS_USE_LETSENCRYPT to any value.
Set OP_TLS_DOMAIN to the (sub-)domain for which to request a certificate. The DNS records for this domain must point to the Connect server.

As long as Connect is running, its HTTPS listener must be reachable on a public IP at port 443 (either by setting OP_HTTPS_PORT=443 or by forwarding traffic at port 443 to the Connect server’s OP_HTTPS_PORT value). This makes sure the Connect server can refresh its Let’s Encrypt certificate.

Manual bus configuration

Manual bus configuration only works with Connect server version 1.5.0 and later.

By default, the two containers (Connect API and Connect sync) automatically discover and connect to the shared bus. This discovery mechanism requires the NET_BROADCAST capability, which you can’t always grant to containers. However, it’s possible to manually configure the shared bus. To manually configure the shared bus:

Assign a static port for the bus by setting the OP_BUS_PORT environment variable to a free port for both containers.
Set the OP_BUS_PEERS environment variable for the Connect API container to [hostname]:[bus port], where hostname is the name of the Connect sync container and bus port the value of OP_BUS_PORT for the Connect sync container.
Set the OP_BUS_PEERS environment variable for the Connect sync container to [hostname]:[bus port], where hostname is the name of the application container and bus port is the value of OP_BUS_PORT for the Connect API container.

The following examples show the configuration values necessary for the Connect API container and the Connect sync container.

Connect API container
Connect sync container

The following example sets environment variables for a Connect API container called op-connect-api.

OP_BUS_PORT=11223
OP_BUS_PEERS=op-connect-api:11223

The following example sets environment variables for a Connect sync container called op-connect-sync.

OP_BUS_PORT=11223
OP_BUS_PEERS=op-connect-sync:11223

Examples

The 1Password Connect repository has example Connect server configurations using Kubernetes, Docker Compose, and AWS Fargate.

​Requirements

​Environment variables

​Data volume

​TLS

​Use your own certificate

​Use Let’s Encrypt

​Manual bus configuration

​Examples

Requirements

Environment variables

Data volume

TLS

Use your own certificate

Use Let’s Encrypt

Manual bus configuration

Examples