Deploying on Linux

Container deployment: Deploying with Docker. Windows Server: Deploying on Windows Server.

Release files ​

The Releases page contains these Linux files:

The .deb packages target Debian and Ubuntu. The .rpm packages target RHEL, Fedora, Rocky Linux and AlmaLinux.

SHA256SUMS contains the SHA-256 checksum of each release file. Verification of the downloaded files:

sha256sum --check --ignore-missing SHA256SUMS

Package installation ​

1. Install the package ​

sudo apt install ./portway_<version>_amd64.deb

sudo dnf install ./portway-<version>-1.x86_64.rpm

The package installs:

2. Set the encryption key ​

Portway reads PORTWAY_ENCRYPTION_KEY from /opt/portway/.env. Set the key before the first start:

echo "PORTWAY_ENCRYPTION_KEY=$(openssl rand -base64 48)" | sudo tee /opt/portway/.env > /dev/null
sudo chown portway:portway /opt/portway/.env
sudo chmod 600 /opt/portway/.env

3. Start the service ​

The package does not enable or start the service:

sudo systemctl enable --now portway

4. Verify ​

The first start creates tokens/, log/ and auth.db in /opt/portway/. Checks:

• curl http://localhost:5000/health/live returns Alive
• http://localhost:5000/docs serves the API reference

Listen address ​

The default listen address is http://localhost:5000. A systemd drop-in sets a different address with ASPNETCORE_URLS:

sudo systemctl edit portway

[Service]
Environment=ASPNETCORE_URLS=http://0.0.0.0:8080

sudo systemctl restart portway

HTTPS requires a reverse proxy. Nginx and Caddy configuration: Versioning.

Package upgrades ​

Install the newer package with the command from Package installation. The package restarts a running service.

The package marks appsettings*.json, endpoints/ and environments/ as configuration files:

Release notes and backup steps: Upgrading Portway.

Package removal ​

sudo apt remove portway

sudo dnf remove portway

Removal stops and disables the service. Files created at runtime (auth.db, mcp.db, tokens/, log/, .env) remain in /opt/portway/.

Archive installation ​

The archive requires the ASP.NET Core Runtime 11.

1. Extract the release ​

sudo useradd --system --home-dir /opt/portway --shell /usr/sbin/nologin portway
sudo mkdir -p /opt/portway
sudo unzip <tag>-Linux_x64.zip -d /opt/portway
sudo chown -R portway:portway /opt/portway

2. Set the encryption key ​

Identical to step 2 of Package installation.

3. Create the systemd unit ​

/etc/systemd/system/portway.service:

[Unit]
Description=Portway API gateway
After=network-online.target
Wants=network-online.target

[Service]
User=portway
WorkingDirectory=/opt/portway
ExecStart=/usr/bin/dotnet /opt/portway/PortwayApi.dll
Restart=on-failure

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now portway

WorkingDirectory is required: Portway reads and writes auth.db, log/, endpoints/ and environments/ relative to the working directory.

Troubleshooting ​

Service log:

sudo journalctl -u portway -e

Backup ​

Back up auth.db, mcp.db, portway.key, .env, .core/, appsettings.overrides.json, environments/, endpoints/ and the file storage directory in /opt/portway/. Upgrades: Upgrading Portway.

Next steps ​

• Configure Environments
• Configure Endpoints
• Security
• Health and Logs