Repository navigation
Expand file tree
/
Copy path.env.example
More file actions
450 lines (386 loc) · 14.1 KB
/
Copy path.env.example
File metadata and controls
450 lines (386 loc) · 14.1 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
# Environment Configuration Template for SMSGate Server
# Copy this file to .env and fill in the values for your deployment.
# This file documents the runtime variables used by the backend and worker.
# Do not commit .env files or real credentials.
# =============================================================================
# RUNTIME AND BOOTSTRAP
# =============================================================================
# Configuration file path
# Purpose: Selects the YAML configuration file loaded after .env values.
# Format: File path (absolute or relative to the process working directory)
# Default: config.yml
# Example: ./configs/config.yml
CONFIG_PATH=./configs/config.yml
# Debug logging
# Purpose: Enables debug-level logging from the shared logger.
# Format: Boolean (true|false)
# Default: false
# Example: true
DEBUG=false
# Optional process timezone
# Purpose: Sets the process timezone used by development tools and the Go runtime.
# This is separate from DATABASE__TIMEZONE.
# Format: IANA timezone name
# Default: System timezone
# Example: UTC
# TZ=UTC
# =============================================================================
# GATEWAY CONFIGURATION
# =============================================================================
# Gateway operation mode
# Purpose: Selects direct FCM delivery or private upstream delivery.
# Required: any value other than public or private fails at startup.
# Format: public or private
# Default: public (configs/config.example.yml ships private)
# Example: private
GATEWAY__MODE=public
# Private registration token
# Purpose: Authenticates new device registrations when private mode is enabled.
# Required for private mode; use a high-entropy value from a secret manager.
# Format: Opaque string
# Default: Empty
# Example: random-high-entropy-token
GATEWAY__PRIVATE_TOKEN=
# Private-mode upstream URL
# Purpose: Base URL used to relay push notifications in private mode.
# Format: Absolute URL
# Default: https://api.sms-gate.app/upstream/v1
# Example: https://api.sms-gate.app/upstream/v1
GATEWAY__UPSTREAM_URL=https://api.sms-gate.app/upstream/v1
# =============================================================================
# HTTP SERVER CONFIGURATION
# =============================================================================
# HTTP listen address
# Purpose: Address and port used by the HTTP server.
# Containers must listen on 0.0.0.0 rather than a loopback address.
# Format: host:port
# Default: :3000
# Example: 0.0.0.0:3000
HTTP__LISTEN=:3000
# Trusted proxy addresses
# Purpose: Enables forwarded-client IP handling for trusted reverse proxies.
# Format: Comma-separated IP addresses or CIDR ranges without spaces
# Default: Empty (no trusted proxies)
# Example: 127.0.0.1
# Example: 10.0.0.0/8
HTTP__PROXIES=
# Public API host
# Purpose: Hostname used when generating public API URLs and links.
# Do not include a scheme or path.
# Format: host[:port]
# Default: Empty (use the request hostname)
# Example: api.example.com
HTTP__API__HOST=
# Public API path prefix
# Purpose: Base path advertised in generated links, in the OpenAPI basePath and in
# the /.well-known/api-catalog document. The routing prefix itself is always /api.
# Format: Absolute path beginning with /
# Default: /api
# Example: /api
HTTP__API__PATH=/api
# OpenAPI documentation
# Purpose: Enables the generated OpenAPI documentation endpoints.
# Keep disabled when the API documentation should not be publicly exposed.
# Format: Boolean (true|false)
# Default: false
# Example: true
HTTP__OPENAPI__ENABLED=false
# =============================================================================
# DATABASE CONFIGURATION
# =============================================================================
# Supported databases: MySQL 8.0.13+ or MariaDB 10.2.7+
# MariaDB LTS is recommended for deployments.
# Database host
# Purpose: Hostname or IP address of the MySQL/MariaDB server.
# Format: Hostname or IP address
# Default: localhost
# Example: localhost
DATABASE__HOST=localhost
# Database port
# Purpose: TCP port of the MySQL/MariaDB server.
# Format: Integer
# Default: 3306
# Example: 3306
DATABASE__PORT=3306
# Database user
# Purpose: Username used to connect to the database.
# Format: String
# Default: sms
# Example: sms
DATABASE__USER=sms
# Database password
# Purpose: Password for database authentication
# Format: String
# Default: sms
# Example: sms
DATABASE__PASSWORD=sms
# Database name
# Purpose: Name of the MySQL/MariaDB database.
# Format: String
# Default: sms
# Example: sms
DATABASE__DATABASE=sms
# Database timezone
# Purpose: Timezone used for database operations and message TTL calculations.
# Format: IANA timezone name
# Default: UTC
# Example: UTC
DATABASE__TIMEZONE=UTC
# Database debug logging
# Purpose: Enables verbose database query logging.
# Format: Boolean (true|false)
# Default: false
# Example: false
DATABASE__DEBUG=false
# Maximum open database connections
# Purpose: Limits concurrent database connections; 0 uses automatic CPU-based sizing.
# Format: Nonnegative integer
# Default: 0 (0 means 4 x CPU count)
# Example: 4
DATABASE__MAX_OPEN_CONNS=0
# Maximum idle database connections
# Purpose: Limits idle database connections; 0 uses automatic CPU-based sizing.
# Format: Nonnegative integer
# Default: 0 (0 means 2 x CPU count)
# Example: 2
DATABASE__MAX_IDLE_CONNS=0
# =============================================================================
# FIREBASE CLOUD MESSAGING (FCM) CONFIGURATION
# =============================================================================
# Firebase service-account credentials
# Purpose: Authenticates direct FCM delivery in public mode.
# Required in public mode; unused in private mode. Supply the value through a
# secret manager rather than committing a service-account file.
# Format: Compact, single-line JSON service-account document
# Default: Empty
# Example: compact service-account JSON
FCM__CREDENTIALS_JSON=
# Push batching debounce
# Purpose: Sets the global interval used to batch queued push notifications.
# Values below 5 seconds are raised to the runtime minimum of 5 seconds.
# Format: Unsigned integer (seconds)
# Default: 0 (effective minimum 5 seconds)
# Example: 5
FCM__DEBOUNCE_SECONDS=5
# Push notification timeout
# Purpose: Limits how long the push client waits for a delivery operation.
# Values below 1 second are raised to the runtime minimum of 1 second.
# Format: Unsigned integer (seconds)
# Default: 0 (effective minimum 1 second)
# Example: 1
FCM__TIMEOUT_SECONDS=1
# =============================================================================
# SERVER-SENT EVENTS (SSE) CONFIGURATION
# =============================================================================
# SSE keep-alive period
# Purpose: Sends keep-alive pings to maintain open SSE connections.
# A value of 0 disables keep-alive pings.
# Format: Unsigned integer (seconds)
# Default: 15
# Example: 15
SSE__KEEP_ALIVE_PERIOD_SECONDS=15
# =============================================================================
# MESSAGES AND QUEUE CONFIGURATION
# =============================================================================
# Message cache TTL
# Purpose: Controls how long cached message data remains available.
# A value of 0 means no expiration.
# Format: Nonnegative integer (seconds)
# Default: 300
# Example: 300
MESSAGES__CACHE_TTL_SECONDS=300
# Message hashing interval
# Purpose: Interval for message hashing (privacy protection)
# Format: Integer (seconds)
# Default: 60
# Example: 60
MESSAGES__HASHING_INTERVAL_SECONDS=60
# Maximum pending messages per device
# Purpose: Blocks new enqueueing when a device has reached the pending limit.
# Values less than or equal to 0 disable this limit.
# Format: Integer
# Default: 0 (disabled)
# Example: 100
MESSAGES__QUEUE__MAX_PENDING=0
# Maximum pending-message age
# Purpose: Blocks enqueueing when a device has messages older than this age.
# A value of 0s disables this check.
# Format: Go duration (for example, 30m or 1h)
# Default: 0s (disabled)
# Example: 1h
MESSAGES__QUEUE__MAX_PENDING_AGE=0s
# Failed-state threshold
# Purpose: Counts recent failed states and blocks enqueueing when the threshold is reached.
# This is a limit window, not a failed-message retention setting.
# Values less than or equal to 0 disable this check.
# Format: Integer
# Default: 0 (disabled)
# Example: 10
MESSAGES__QUEUE__MAX_FAILED=0
# Failed-state threshold window
# Purpose: Defines the time window used with MESSAGES__QUEUE__MAX_FAILED.
# Both values must be greater than 0 for the failed-state limit to be active.
# Format: Go duration (for example, 24h; d and w are not valid units)
# Default: 0s (disabled)
# Example: 24h
MESSAGES__QUEUE__MAX_FAILED_AGE=0s
# Queue-statistics refresh interval
# Purpose: Controls how often queue-limit statistics are refreshed.
# Format: Positive Go duration
# Default: 5s
# Example: 5s
MESSAGES__QUEUE__STATS_REFRESH_INTERVAL=5s
# Queue-statistics cache TTL
# Purpose: Controls how long refreshed queue-limit statistics are cached.
# Format: Positive Go duration
# Default: 60s
# Example: 60s
MESSAGES__QUEUE__STATS_CACHE_TTL=60s
# =============================================================================
# CACHE AND PUB/SUB CONFIGURATION
# =============================================================================
# Cache URL
# Purpose: Selects the backend cache implementation.
# Use a shared Redis instance when running multiple backend replicas.
# Format: memory:// or redis:// URL
# Default: memory://
# Example: memory://
# Example: redis://localhost:6379/0
CACHE__URL=memory://
# Cache sweep interval
# Purpose: How often expired cache entries are evicted from every cache the gateway created.
# Format: Positive Go duration
# Default: 1m
# Note: the app fails at startup if this is not positive while the sweeper is enabled
# Example: 1m
CACHE__SWEEP_INTERVAL=1m
# Pub/Sub URL
# Purpose: Selects the backend pub/sub implementation.
# Use a shared Redis instance when running multiple backend replicas.
# Format: memory:// or redis:// URL
# Default: memory://
# Example: memory://
# Example: redis://localhost:6379/1
PUBSUB__URL=memory://
# Pub/Sub buffer size
# Purpose: Sets the subscriber channel buffer size; 0 creates unbuffered channels.
# Format: Unsigned integer
# Default: 128
# Example: 128
PUBSUB__BUFFER_SIZE=128
# =============================================================================
# JWT AUTHENTICATION CONFIGURATION
# =============================================================================
# JWT signing secret
# Purpose: Signs and verifies JWT access and refresh tokens.
# An empty value disables JWT functionality; a non-empty value must be at least
# 32 bytes. Use a high-entropy value from a secret manager.
# Format: Secret string
# Default: Empty (JWT disabled)
# Example: random-high-entropy-secret
JWT__SECRET=
# JWT access-token lifetime
# Purpose: Controls how long an issued access token remains valid.
# Format: Positive Go duration
# Default: 15m
# Example: 15m
JWT__ACCESS_TTL=15m
# JWT refresh-token lifetime
# Purpose: Controls how long an issued refresh token remains valid.
# Must be greater than JWT__ACCESS_TTL when JWT is enabled.
# Format: Positive Go duration
# Default: 720h
# Example: 720h
JWT__REFRESH_TTL=720h
# JWT issuer
# Purpose: Sets the issuer claim included in issued tokens.
# Format: Stable string identifier
# Default: sms-gate.app
# Example: sms-gate.app
JWT__ISSUER=sms-gate.app
# =============================================================================
# OTP CONFIGURATION
# =============================================================================
# OTP enabled
# Purpose: Enable one-time code authentication for device registration
# Format: Boolean (true/false)
# Default: true
# Example: true
OTP__ENABLED=true
# OTP code length
# Purpose: Length of generated OTP codes (minimum 6)
# Format: Integer
# Default: 6
# Example: 6
OTP__LENGTH=6
# OTP TTL
# Purpose: Time-to-live for one-time passwords in seconds
# Format: Integer (seconds)
# Default: 60
# Example: 60
OTP__TTL=60
# OTP retries
# Purpose: Number of retry attempts for OTP generation (handles collision)
# Format: Integer
# Default: 3
# Example: 3
OTP__RETRIES=3
# =============================================================================
# BACKGROUND WORKER CONFIGURATION
# =============================================================================
# These settings are used by the worker command. Duration values use Go syntax;
# use 24h, 168h, or 8760h rather than d or w.
# Message hashing task interval
# Purpose: Schedules periodic hashing of processed message content and phone numbers.
# Format: Go duration
# Default: 168h
# Example: 168h
TASKS__MESSAGES_HASHING__INTERVAL=168h
# Message cleanup task interval
# Purpose: Schedules deletion of messages that exceed the configured maximum age.
# Format: Go duration
# Default: 24h
# Example: 24h
TASKS__MESSAGES_CLEANUP__INTERVAL=24h
# Message cleanup maximum age
# Purpose: Sets the retention age for messages before cleanup removes them.
# Format: Go duration
# Default: 720h
# Example: 720h
TASKS__MESSAGES_CLEANUP__MAX_AGE=720h
# Device cleanup task interval
# Purpose: Schedules removal of inactive devices that exceed the maximum age.
# Format: Go duration
# Default: 24h
# Example: 24h
TASKS__DEVICES_CLEANUP__INTERVAL=24h
# Device cleanup maximum age
# Purpose: Sets the retention age for inactive devices before removal.
# Format: Go duration
# Default: 8760h
# Example: 8760h
TASKS__DEVICES_CLEANUP__MAX_AGE=8760h
# Token cleanup task interval
# Purpose: Schedules removal of tokens that are expired beyond the grace period.
# Format: Go duration
# Default: 24h
# Example: 24h
TASKS__TOKENS_CLEANUP__INTERVAL=24h
# Token cleanup grace period
# Purpose: Keeps recently expired tokens briefly before deleting them.
# Format: Go duration
# Default: 1h
# Example: 1h
TASKS__TOKENS_CLEANUP__MAX_AGE=1h
# Inbox cleanup task interval
# Purpose: Schedules removal of inbox messages that exceed the configured maximum age.
# Format: Go duration
# Default: 24h
# Example: 24h
TASKS__INBOX_CLEANUP__INTERVAL=24h
# Inbox cleanup maximum age
# Purpose: Sets the retention age for inbox messages and attachments before cleanup.
# Format: Go duration
# Default: 720h
# Example: 720h
TASKS__INBOX_CLEANUP__MAX_AGE=720h