docs: warn when adding attachments without network isolation

Attachments require network_isolation.enabled = true because Docker's
default bridge network does not provide DNS resolution between containers.
Without it, apps cannot reach attachments by hostname (e.g., postgres:5432).

Changes:
- CLI warns when adding attachment locally without network isolation
- Updated docs/config/attachments.md with Requirements section
- Updated docs/cli/attachments.md with Requirements section
- Updated CLI help text for 'attachments add' command

commit: 3cd0f9c74814f9573b54268b78d127a4dd12f874
author: brice · 9mo ago · 2026-01-17 15:46 UTC
parent: a43bd67
signature: GPG VerifiedCD88F9E564E0102646FB6077A1A07C7C7C3E349D · arch-gpg Verified for the committer email

3 files · +33 -1

M docs/cli/attachments.md +6 -0


@@ -2,6 +2,12 @@
2	2
3	3		Manage attachments on local or remote Gordon instances.
4	4
	5	+	## Requirements
	6	+
	7	+	Attachments require `network_isolation.enabled = true` in your configuration. Without network isolation, containers use Docker's default bridge network which does not provide DNS resolution - your app won't be able to reach attachments by hostname (e.g., `postgres:5432`).
	8	+
	9	+	The CLI will warn you if you try to add an attachment without network isolation enabled.
	10	+
5	11		## gordon attachments
6	12
7	13		### Subcommands


@@ -2,6 +2,12 @@
2		2
3	Manage attachments on local or remote Gordon instances.	3		Manage attachments on local or remote Gordon instances.
4		4
		5	+	## Requirements
		6	+
		7	+	Attachments require `network_isolation.enabled = true` in your configuration. Without network isolation, containers use Docker's default bridge network which does not provide DNS resolution - your app won't be able to reach attachments by hostname (e.g., `postgres:5432`).
		8	+
		9	+	The CLI will warn you if you try to add an attachment without network isolation enabled.
		10	+
5	## gordon attachments	11		## gordon attachments
6		12
7	### Subcommands	13		### Subcommands

M docs/config/attachments.md +11 -0


@@ -2,6 +2,17 @@
2	2
3	3		Attach service dependencies (databases, caches, queues) to your applications.
4	4
	5	+	## Requirements
	6	+
	7	+	Network isolation must be enabled for attachments to work properly:
	8	+
	9	+	```toml
	10	+	[network_isolation]
	11	+	enabled = true
	12	+	```
	13	+
	14	+	Without network isolation, containers run on Docker's default bridge network which does not provide DNS resolution. Your application won't be able to reach attachments by hostname (e.g., `postgres:5432`).
	15	+
5	16		## Configuration
6	17
7	18		```toml


@@ -2,6 +2,17 @@
2		2
3	Attach service dependencies (databases, caches, queues) to your applications.	3		Attach service dependencies (databases, caches, queues) to your applications.
4		4
		5	+	## Requirements
		6	+
		7	+	Network isolation must be enabled for attachments to work properly:
		8	+
		9	+	```toml
		10	+	[network_isolation]
		11	+	enabled = true
		12	+	```
		13	+
		14	+	Without network isolation, containers run on Docker's default bridge network which does not provide DNS resolution. Your application won't be able to reach attachments by hostname (e.g., `postgres:5432`).
		15	+
5	## Configuration	16		## Configuration
6		17
7	```toml	18		```toml

M internal/adapters/in/cli/attachments.go +16 -1


@@ -180,8 +180,13 @@ func newAttachmentsAddCmd() *cobra.Command {
180	180		Short: "Add an attachment",
181	181		Long: `Add a container attachment to a domain or network group.
182	182
	183	+	Note: Attachments require network_isolation.enabled = true in your configuration.
	184	+	Without network isolation, containers use Docker's default bridge network which
	185	+	does not provide DNS resolution - your app won't be able to reach attachments
	186	+	by hostname (e.g., 'postgres:5432').
	187	+
183	188		Examples:
184		-	gordon attachments add app.example.com postgres:15
	189	+	gordon attachments add app.example.com postgres:18
185	190		gordon attachments add backend redis:7-alpine
186	191		gordon --remote https://gordon.mydomain.com attachments add api.mydomain.com memcached:latest`,
187	192		Args: cobra.ExactArgs(2),

@@ -200,6 +205,16 @@ Examples:
200	205		if err != nil {
201	206		return fmt.Errorf("failed to initialize local services: %w", err)
202	207		}
	208	+
	209	+	// Warn if network isolation is disabled
	210	+	if !local.GetConfigService().IsNetworkIsolationEnabled() {
	211	+	fmt.Println(styles.RenderWarning("network_isolation.enabled = false"))
	212	+	fmt.Println(styles.Theme.Muted.Render(" Attachments require network isolation for DNS resolution."))
	213	+	fmt.Println(styles.Theme.Muted.Render(" Without it, your app cannot reach attachments by hostname."))
	214	+	fmt.Println(styles.Theme.Muted.Render(" Enable with: [network_isolation] enabled = true"))
	215	+	fmt.Println()
	216	+	}
	217	+
203	218		if err := local.GetConfigService().AddAttachment(ctx, target, image); err != nil {
204	219		return fmt.Errorf("failed to add attachment: %w", err)
205	220		}


@@ -180,8 +180,13 @@ func newAttachmentsAddCmd() *cobra.Command {
180		Short: "Add an attachment",	180		Short: "Add an attachment",
181		Long: `Add a container attachment to a domain or network group.	181		Long: `Add a container attachment to a domain or network group.
182			182
			183	+	Note: Attachments require network_isolation.enabled = true in your configuration.
			184	+	Without network isolation, containers use Docker's default bridge network which
			185	+	does not provide DNS resolution - your app won't be able to reach attachments
			186	+	by hostname (e.g., 'postgres:5432').
			187	+
183		Examples:	188		Examples:
184	-	gordon attachments add app.example.com postgres:15	189	+	gordon attachments add app.example.com postgres:18
185		gordon attachments add backend redis:7-alpine	190		gordon attachments add backend redis:7-alpine
186		gordon --remote https://gordon.mydomain.com attachments add api.mydomain.com memcached:latest`,	191		gordon --remote https://gordon.mydomain.com attachments add api.mydomain.com memcached:latest`,
187		Args: cobra.ExactArgs(2),	192		Args: cobra.ExactArgs(2),

@@ -200,6 +205,16 @@ Examples:
200		if err != nil {	205		if err != nil {
201		return fmt.Errorf("failed to initialize local services: %w", err)	206		return fmt.Errorf("failed to initialize local services: %w", err)
202		}	207		}
			208	+
			209	+	// Warn if network isolation is disabled
			210	+	if !local.GetConfigService().IsNetworkIsolationEnabled() {
			211	+	fmt.Println(styles.RenderWarning("network_isolation.enabled = false"))
			212	+	fmt.Println(styles.Theme.Muted.Render(" Attachments require network isolation for DNS resolution."))
			213	+	fmt.Println(styles.Theme.Muted.Render(" Without it, your app cannot reach attachments by hostname."))
			214	+	fmt.Println(styles.Theme.Muted.Render(" Enable with: [network_isolation] enabled = true"))
			215	+	fmt.Println()
			216	+	}
			217	+
203		if err := local.GetConfigService().AddAttachment(ctx, target, image); err != nil {	218		if err := local.GetConfigService().AddAttachment(ctx, target, image); err != nil {
204		return fmt.Errorf("failed to add attachment: %w", err)	219		return fmt.Errorf("failed to add attachment: %w", err)
205		}	220		}