Custom proxy config

Synq writes the OpenResty (nginx) configuration for every domain itself. For the few cases its settings don't cover, an organization admin can add a handful of raw directives to one domain. Synq checks them, tests the whole edge configuration and puts the previous version back automatically if the edge refuses it, so a typo can't take your other sites down.

Who can use it

• Reading: anyone who can see the domain can open the dialog and view the rendered config.
• Editing: organization owners and admins. Members with the Member role see "Only organization admins can change this. You can still see the rendered config." The API needs the domain:admin permission.
• Availability: every domain of a project on your servers, including free subdomains on your apps domain (they are ordinary domains). It isn't offered for a managed subdomain this server doesn't route ("Custom config is not available for this domain.").

Edit a domain's config

To remove your directives, empty both boxes and save.

What happens when you save

1. Validation. The API checks every line before anything is stored (see Rules). A refused snippet is not saved; the error lists each problem with its box and line, for example server line 2: `include` is not allowed: it loads other files into the edge config.
2. Apply. The config is stored on the domain and the project's live routes are re-applied. The edge writes the new vhost file, runs openresty -t on the whole configuration and reloads.
3. Rollback. If the test or the reload fails, the edge restores the previous vhost file and Synq restores the previous stored config. Your draft stays in the boxes so you can fix it.

The dialog reports one of:

Your directives are stored with the domain and rendered into its vhost every time Synq writes it (a deploy, a certificate renewal, a route change), so they survive redeploys.

Every save that reaches the edge is recorded in the Audit log as domain.custom_config_updated or, when the edge refused it, domain.custom_config_rejected. The entry records line counts, sizes and directive names, not the raw text, since a snippet may contain a header value or token.

Rendered config

Rendered config (read-only) shows the domain's vhost file exactly as the edge holds it. Your lines are highlighted between the markers # synq-custom-config: begin (server) (or (location)) and # synq-custom-config: end. Press Refresh to read it again. Before the domain is verified or the project has deployed, it says that no vhost exists yet.

Rules

Raw config can't be proven safe by reading it, so the checks are layered: Synq refuses what must never reach a shared edge, checks the structure, and then lets openresty -t have the final word.

Size and structure

• At most 8,192 bytes and 200 lines per box, and blocks nested at most 4 deep.
• Every statement ends with ;, and braces must balance. A snippet can't close the block it's placed in.
• No braces inside quoted values or comments, quoted values stay on one line, and no control characters.
• Put location blocks in the Server block box, not in location / block.

Refused directives

The dialog summarizes the list: "Not allowed: include, load_module, Lua and njs code, init_* and worker_* settings, env, user, certificate paths, temp and cache paths, logs or root/alias outside this app, and upstreams on Synq's own ports." In full:

Directives with restricted arguments

Examples

Add an HSTS header, so browsers remember to use HTTPS (Server block):

add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

Keep response headers in the Server block box. An add_header inside location / makes nginx ignore every add_header from the server level for that location, including headers Synq sets for you.

Answer robots.txt at the edge for a staging site (Server block):

location = /robots.txt {
    default_type text/plain;
    return 200 "User-agent: *\nDisallow: /\n";
}

Hide a header your framework adds and pass an extra one to the app (location / block):

proxy_hide_header X-Powered-By;
proxy_set_header X-Forwarded-Host $host;

From the API

curl -H "Authorization: Bearer $SYNQ_TOKEN" \
  "$SYNQ_URL/api/domains/<domainId>/custom-config"

curl -X PUT -H "Authorization: Bearer $SYNQ_TOKEN" -H "Content-Type: application/json" \
  -d '{"server":"add_header X-Frame-Options \"DENY\" always;","location":""}' \
  "$SYNQ_URL/api/domains/<domainId>/custom-config"

GET returns the stored server and location text, whether you may edit it, the limits and the rendered vhost. PUT replaces both parts (an omitted field clears that part) and returns the same view plus a status of applied, saved, rolled_back or unchanged; a rolled_back result carries the edge's error in message.

Related