Upgrade from v0.9

هذا المحتوى غير متوفر بلغتك بعد.

Upgrade from v0.9 to v1.1.0

Step-by-step guide for upgrading an ɳSelf v0.9.x project to v1.1.0.

Before you start

What changed in v1.0.0:

The CLI was rewritten from Bash to Go. It is now a single binary.
Plugin format changed from shell scripts to signed Go bundles. All v0.9 plugins must be re-installed.
The environment file layout changed from a single .env to a cascade: .env.dev → .env.local → .env.staging/.env.prod → .env.secrets → .env.computed.
The nginx config moved from nginx/ (flat) to nginx/sites/ (structured).
.nself/config changed from a plain file to a directory.
nself (the v0.9 bootstrap script) is no longer used.

What nself migrate does automatically:

Stops running containers.
Backs up your current project state to .nself/backup/{timestamp}/.
Moves nginx configs to nginx/sites/.
Regenerates docker-compose.yml, nginx, and SSL certificates for v1.

What you must do manually after migration:

Re-enter your license key: nself license set <key>.
Re-install each plugin: nself plugin install <name>.

Step 1: Upgrade the CLI

macOS (Homebrew)

brew upgrade nself-org/nself/nself
nself --version
# Expected: nself v1.1.0 (darwin/arm64)

Linux

curl -fsSL https://install.nself.org | bash
nself --version

Step 2: Run the migration

Navigate to your v0.9 project directory and run:

cd ~/my-nself-project

# First, scan to see what will be migrated
nself migrate detect

# Run the full migration
nself migrate run

The migration is idempotent: running it on an already-migrated project exits cleanly with no changes.

Verify the migration completed:

nself migrate detect
# Expected: No v1 artifacts detected. This project is ready for nSelf v2.

Step 3: Re-install plugins

Plugin signatures changed in v1.0.0. Every v0.9 plugin must be re-installed.

# Re-enter your license key
nself license set nself_pro_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Re-install plugins (use your actual plugin list)
nself plugin install ai mux claw voice browser google notify cron

After running nself migrate run, the CLI prints a warning with the exact plugin list from your v0.9 .env and the commands to re-install them.

Step 4: Verify the stack

nself build
nself start
nself doctor

Command changes

v0.9 command	v1.1.0 equivalent	Notes
`./nself start`	`�P1� start`	Go binary, no bootstrap script
`./nself stop`	`�P1� stop`
`./nself status`	`�P1� status`
`./nself build`	`�P1� build`
`./nself logs`	`�P1� logs`
`./nself update`	`�P1� update`
`./nself doctor`	`�P1� doctor`
`./nself plugin install <name>`	`�P1� plugin install <name>`	New signed format
`./nself plugin list`	`�P1� plugin list`
`./nself plugin remove <name>`	`�P1� plugin remove <name>`
`./nself license set <key>`	`�P1� license set <key>`
`./nself license info`	`�P1� license info`
`./nself migrate`	`�P1� migrate`	New in v1.0.0
`./nself backup`	`�P1� backup`
`./nself restore`	`�P1� restore`
`./nself db migrate`	`�P1� db migrate`
`./nself db reset`	`�P1� db reset`
`./nself ssl renew`	`�P1� ssl renew`
`./nself config get <key>`	`�P1� config get <key>`
`./nself config set <key> <val>`	`�P1� config set <key> <val>`
`./nself env show`	`�P1� env show`
`./nself admin start`	`�P1� admin start`
`nself up`	`�P1� start` or `�P2� up`	`up` is now an alias

Environment file changes

v0.9: Single .env file with all configuration including secrets.

v1.1.0: Cascade of env files:

.env.dev        Team-shared defaults (tracked in git)
.env.local      Your machine-specific overrides (gitignored)
.env.staging    Staging overrides (tracked)
.env.prod       Production overrides (tracked, no real secrets)
.env.secrets    Real secrets: API keys, passwords (gitignored)
.env.computed   Generated by nself build (never edit manually)

The migration handles this automatically. After running nself migrate run, your old .env is backed up and �P1� build generates a compatible v1 configuration.

Plugin name changes

All v0.9 plugins used shell scripts. v1.1.0 uses signed Go bundles. Plugins are incompatible across versions.

v0.9 plugin name	v1.1.0 plugin name
`nself`	`ai`
`nself`	`claw`
`nself`	`mux`
`nself`	`voice`
`nself`	`browser`
`nself`	`google`
`nself`	`notify`
`nself`	`cron`
`nself`	`chat`
`nself`	`livekit`
`nself`	`recording`
`nself`	`moderation`
`nself`	`bots`
`nself`	`realtime`
`nself`	`media-processing`
`nself`	`streaming`
`nself`	`epg`
`nself`	`tmdb`
`nself`	`social`

Troubleshooting

Docker version too old

Error: Docker 24 or later is required (found: 20.10.x)

Upgrade Docker:

# macOS
brew upgrade docker

# Ubuntu/Debian
sudo apt-get update && sudo apt-get install docker-ce

Port conflicts

Error: port 5432 is already in use by process: postgresql (pid 1234)

Stop the conflicting service:

# macOS
brew services stop postgresql

# Linux
sudo systemctl stop postgresql

License key rejected after migration

nself license set nself_pro_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
nself license info

Plugin name not found

v0.9 used nself prefix; v1.1.0 uses short names:

# Correct
nself plugin install ai

# Wrong
nself plugin install nself-ai

Migration fails midway

nself migrate rollback --list
nself migrate rollback

nself doctor reports issues after migration

nself doctor --full
nself doctor --check-legacy

Rollback

# List available backups
nself migrate rollback --list

# Restore the most recent backup
nself migrate rollback

# Restore a specific backup by timestamp
nself migrate rollback --backup 20260420-143022

Automated testing

The migration path is covered by a CI fixture (cli/internal/migration/testdata/v0.9-fixture/) that runs on every PR via .github/workflows/migration-fixture.yml.