# How to reference file in HQ config file in EC2 instance

**URL:** <https://ask.lenses.io/t/how-to-reference-file-in-hq-config-file-in-ec2-instance/468>\
**Category:** General\
**Created:** [April 1, 2026, 8:47am UTC](https://ask.lenses.io/t/how-to-reference-file-in-hq-config-file-in-ec2-instance/468 "2026-04-01T08:47:26Z")\
**Posts on this page:** 2\
**Page:** 1

<div class="post-metadata">

**Author:** ![superbrain\_bug](https://avatars.discourse-cdn.com/v4/letter/s/bb73d2/32.png) [@superbrain\_bug](https://ask.lenses.io/u/superbrain_bug)\
**Post date:** [April 1, 2026, 8:47am UTC](https://ask.lenses.io/t/how-to-reference-file-in-hq-config-file-in-ec2-instance/468/1 "2026-04-01T08:47:26Z")

</div>

Hello Lenses Support Team,

We would like to raise a request regarding the current setup for Lenses login and SAML/SSO integration.

At present, the SAML/SSO metadata file needs to be embedded directly within the configuration file. From an operational and formatting standpoint, this approach is not very convenient to manage or maintain. Our current SAML/SSO metadata is expired so we need to update.

We believe it would be more efficient if the SAML/SSO metadata could be stored in a separate file and referenced during the Lenses HQ service startup. This would improve readability, simplify certificate updates, and reduce the risk of formatting issues within the configuration.

Could you please advise if this approach is supported, or if there are any recommended best practices to achieve this?

We look forward to your guidance on this matter.

---

<div class="post-metadata">

**Author:** ![iMajna](https://dub1.discourse-cdn.com/flex017/user_avatar/ask.lenses.io/imajna/32/116_2.png) [@iMajna](https://ask.lenses.io/u/iMajna)\
**Post date:** [April 1, 2026, 2:02pm UTC](https://ask.lenses.io/t/how-to-reference-file-in-hq-config-file-in-ec2-instance/468/2 "2026-04-01T14:02:02Z")

</div>

This is how to configure HQ to work with metadata.xml file on EC2 through env var

### **Configuration File (config.yaml)**

The config file uses environment variable substitution with `$(VAR_NAME)` syntax:

```yaml
auth:
  saml:
    enabled: true
    baseURL: https://your-hq-domain.com
    entityID: https://your-hq-domain.com
    metadata: $(SAML_METADATA)
    userCreationMode: sso
    groupMembershipMode: sso
    uiRootURL: /
    groupAttributeKey: groups
    authnRequestSignature:
      enabled: false

```

### **Setting Up SAML Metadata on EC2**

**Step 1: Save your IdP metadata to a file**  
_# Create the metadata file. Please make sure that your metadata.xml **file is correctly indented** _

```bash
cat > /etc/lenses-hq/saml-metadata.xml << 'EOF'
<?xml version="1.0" encoding="UTF-8"?><md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" ...>
  <!-- Your full SAML IdP metadata XML here -->
</md:EntityDescriptor>
EOF

```

**Step 2: Export the environment variable**  
_# Load the file content into an environment variable_

```bash
export SAML_METADATA="$(cat /etc/lenses-hq/saml-metadata.xml)"

```

**Step 3: Start Lenses HQ**  
_# Start HQ with the config file - it will substitute $(SAML\_METADATA)_

**Systemd Service Example**

For persistent configuration with systemd, create an environment file:  
**/etc/lenses-hq/env**

```bash
LENSESHQ_LICENSE=your-license-key
LENSESHQ_PG_USERNAME=postgres
LENSESHQ_PG_PASSWORD=your-db-password

```

**/etc/systemd/system/lenses-hq.service**

```bash
[Unit]
Description=Lenses HQ
After=network.target

[Service]
Type=simple
User=lenses
EnvironmentFile=/etc/lenses-hq/env
ExecStartPre=/bin/bash -c 'echo "SAML_METADATA=$(cat /etc/lenses-hq/saml-metadata.xml)" >> /run/lenses-hq/env'
ExecStart=/opt/lenses-hq/bin/lenses-hq /etc/lenses-hq/config.yaml
Restart=on-failure

[Install]
WantedBy=multi-user.target

```

Or use a wrapper script:  
**/opt/lenses-hq/bin/start-hq.sh**

```bash
#!/bin/bash
set -e

# Load SAML metadata from file into environment variable
export SAML_METADATA="$(cat /etc/lenses-hq/saml-metadata.xml)"

# Load other environment variables
source /etc/lenses-hq/env

# Start Lenses HQ
exec /opt/lenses-hq/bin/lenses-hq /etc/lenses-hq/config.yaml

```

### **Verifying the Setup**

```bash
# Verify the metadata file exists and is valid XML
cat /etc/lenses-hq/saml-metadata.xml | head -5

# Verify the environment variable is set correctly
export SAML_METADATA="$(cat /etc/lenses-hq/saml-metadata.xml)"
echo "SAML_METADATA length: ${#SAML_METADATA} characters"

# Test the first 100 characters
echo "$SAML_METADATA" | head -c 100

```

Hope this helps!

Kind regards,  
Ivan