Configuration

The configuration file is published to config/netsons-deploy.php.

Strategy

'strategy' => env('NETSONS_DEPLOY_STRATEGY', 'ftp'),

Choose between ftp or git. See FTP Strategy and Git Strategy.

SSH

'ssh' => [
    'host' => env('NETSONS_SSH_HOST'),
    'port' => env('NETSONS_SSH_PORT', 65100),
    'user' => env('NETSONS_SSH_USER'),
    'retries' => env('NETSONS_SSH_RETRIES', 3),
    'retry_delay' => env('NETSONS_SSH_RETRY_DELAY', 10),
    'connect_timeout' => env('NETSONS_SSH_CONNECT_TIMEOUT', 30),
],

• port defaults to 65100 — the standard SSH port on Netsons shared hosting.
• retries — max SSH connection retry attempts (default 3). Only connection failures (exit code 255) are retried.
• retry_delay — seconds between retries (default 10).
• connect_timeout — SSH connection timeout in seconds (default 30). Fails fast instead of the system default (~2 minutes).

PHP Binary

'php_binary' => env('NETSONS_PHP_BINARY', '/usr/local/bin/ea-php84'),

Common values: /usr/local/bin/ea-php82, ea-php83, ea-php84.

Composer Binary

'composer_binary' => env('NETSONS_COMPOSER_BINARY', '/usr/local/bin/composer'),

The remote Composer binary path. The default /usr/local/bin/composer is the standard path on Netsons shared hosting. If your server has Composer at a different location (e.g., /opt/cpanel/composer/bin/composer), update this value.

Deploy Path

'deploy_path' => env('NETSONS_DEPLOY_PATH', 'public_html'),

Remote directory relative to your home directory.

FTP Settings

'ftp' => [
    'host' => env('NETSONS_FTP_HOST'),
    'port' => env('NETSONS_FTP_PORT', 21),
    'user' => env('NETSONS_FTP_USER'),
    'password' => env('NETSONS_FTP_PASS'),
    'protocol' => env('NETSONS_FTP_PROTOCOL', 'ftp'),
    'root_path' => env('NETSONS_FTP_ROOT_PATH', ''),
],

Only used with the FTP strategy.

FTP Root Path

The root_path controls how the FTP server-dir is computed:

• Empty (default) — FTP root is your home directory (/home/user/). The workflow uses DEPLOY_PATH/releases/....
• Set to site directory — FTP root is scoped to the site (/home/user/mysite.com/). The workflow uses releases/... directly.

Check your FTP root in cPanel > Files > FTP Accounts > Configure FTP Client.

Git Settings

'git' => [
    'repo' => env('NETSONS_GIT_REPO'),
    'branch' => env('NETSONS_GIT_BRANCH', 'main'),
],

Only used with the Git strategy. The repo URL must use HTTPS format (e.g., https://github.com/user/repo.git). SSH format does not work — Netsons blocks outbound SSH on port 22.

Release Management

'releases' => [
    'keep' => env('NETSONS_RELEASES_KEEP', 5),
],

Number of releases to retain. Older releases are removed after each deployment.

.htaccess

'htaccess' => [
    'root' => true,
    'public' => true,
],

• root — rewrites all requests to the public/ subdirectory
• public — ensures Laravel’s rewrite rules are in public/.htaccess

Environments

'environments' => [
    'stage' => ['htaccess_root' => true],
    'production' => ['htaccess_root' => true],
],

Per-environment overrides.

.env Mapping

'env_mapping' => [
    // 'DB_PASSWORD' => 'PROD_DB_PASSWORD',
],

Maps .env keys to GitHub secret names for injection during deployment.

Note

The actual env variable management is handled via netsons-deploy.json. See the section below.

Post-Deploy

'post_deploy' => [
    'clear_cache' => true,
    'migrate' => true,
    'cache_config' => true,
    'cache_routes' => true,
    'cache_views' => true,
    'cache_events' => true,
    'queue_restart' => true,
],

Toggle individual post-deploy steps. The workflow always runs package:discover --ansi before cache commands.

Seeders

'seeders' => [
    // 'DatabaseSeeder',
],

Run on the first deploy only. A .first_deploy flag file controls this.

Seeders can also be configured interactively during netsons:install and stored in netsons-deploy.json. When both are set, netsons-deploy.json takes precedence.

During install, the command auto-detects seeders from your composer.json:

Package	Suggested seeders
(always)	DatabaseSeeder
spatie/laravel-permission	RoleSeeder, PermissionSeeder

See the First Deployment guide for details.

---

netsons-deploy.json

The netsons-deploy.json file in your project root stores additional deployment configuration. It is created by netsons:install and managed by netsons:env.

During netsons:install, the installer auto-detects variables from your .env.example:

• Secret-backed — DB_DATABASE, DB_USERNAME, DB_PASSWORD, MAIL_USERNAME, MAIL_PASSWORD, REDIS_PASSWORD, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
• Static — any key with a non-placeholder value, excluding infrastructure prefixes (APP_*, DB_*, REDIS_*, AWS_*, LOG_*, CACHE_*) and placeholder values. MAIL_* keys like MAIL_SCHEME are detected as static; only MAIL_USERNAME/MAIL_PASSWORD are secret-backed.

Static values can be edited after selection. When reconfiguring, the JSON is reset to defaults.

Schema

{
    "env_mapping": {
        "DB_DATABASE": "DB_DATABASE",
        "DB_USERNAME": "DB_USERNAME",
        "DB_PASSWORD": "DB_PASSWORD"
    },
    "env_static": {
        "SESSION_DRIVER": "database",
        "LARAVEL_PDF_DRIVER": "dompdf"
    },
    "build_env": {
        "VITE_APP_NAME": "My App"
    },
    "custom_commands": [
        "event-sourcing:cache-event-handlers 2>/dev/null || true"
    ],
    "seeders": [
        "DatabaseSeeder"
    ],
    "notifications": {
        "slack_webhook_secret": "SLACK_WEBHOOK_DEBUG"
    }
}

env_mapping

Maps .env variable names to GitHub Secret names. Values are injected into the remote .env file with proper sed escaping for special characters.

env_static

Static .env values that are fixed per deployment (not from secrets). Written directly into the workflow.

"env_static": {
    "SESSION_DRIVER": "database",
    "LARAVEL_PDF_DRIVER": "dompdf"
}

build_env

Environment variables available during the asset build step (yarn build / npm run build).

"build_env": {
    "VITE_APP_NAME": "My Application"
}

custom_commands

Additional artisan commands for the post-deploy cache rebuild phase. Run after standard cache commands and before queue:restart.

"custom_commands": [
    "event-sourcing:cache-event-handlers 2>/dev/null || true",
    "permission:cache-reset"
]

Common examples:

Package	Command
Spatie Event Sourcing	event-sourcing:cache-event-handlers 2>/dev/null || true
Spatie Permission	permission:cache-reset
Laravel Horizon	horizon:terminate
Laravel Telescope	telescope:prune
Laravel Scout	scout:sync-index-settings

notifications

Optional Slack deploy notifications.

"notifications": {
    "slack_webhook_secret": "SLACK_WEBHOOK_DEBUG"
}

The value is the GitHub Secret name containing the Slack webhook URL.

envaudit

Enables envaudit .env validation after deployment. When enabled, the workflow downloads the remote .env and validates it before proceeding with migrations.

"envaudit": true

See the envaudit CI integration guide for details.