• English

      • Deployment and Source Management

      Prerequisites

      Before reading this page, make sure you have your first Portal running by following the AI Portal Quick Start.

      Portal source lives in three places: the local dev workspace, source storage, and the deployed artifacts. nb portal keeps them in sync.

      The full lifecycle

      The day-to-day loop looks like this:

      dev (local development) → push (push source) → deploy (build and deploy)

      Where:

      1. nb portal dev <portal> — Start the local dev server, change code and see the result
      2. nb portal push <portal> — Push local source changes to source storage
      3. nb portal deploy <portal> — Build and deploy, making changes live for users

      If you're picking up a Portal a colleague already created, or you've switched machines, pull it locally first:

      nb portal list                 # See which Portals exist
nb portal pull customer        # Pull the source locally
nb portal dev customer         # Start developing

      pull downloads and unpacks the source into the dev workspace, ./<portal> by default, or elsewhere with --path. Dependencies are installed automatically; add --no-install to skip that in CI or when you'd rather install them yourself.

      After a successful pull, the dev workspace location is recorded in the CLI env config, so dev, push, and deploy all read the source from there without you specifying it every time.

      Adding a Portal

      An application can have several Portals with separate pages and permissions but shared data. Say one entry for internal staff and one for external customers:

      nb portal create customer

      Creating generates ./customer in the current directory as the dev workspace from the @nocobase/portal-template-default template, writes .env and .env.local, then installs dependencies. Use --path to put it elsewhere.

      A Portal name can only contain lowercase letters, digits, underscores, and hyphens, and must start with a lowercase letter or digit.

      source storage

      Portal source can be kept in two places:

      ModeDescriptionWhen to use
      nocobaseThe default, with source managed by NocoBase's source storageGetting started quickly, solo development, no code review needed
      gitSource saved to a Git repository you specifyTeam collaboration, code review, CI integration

      The default nocobase is the fastest to start with, since you don't need a repository first. It has no version history though, so a bad change can only be rolled back by overwriting everything. If this Portal will be iterated on long term, move it to Git early.

      Switching to Git

      create only generates the dev workspace; source storage configuration goes through config. You can switch any time after creating:

      nb portal config customer \
  --source-storage git \
  --git-repo git@github.com:nocobase/customer-portal.git

nb portal push customer --message "Move customer portal source to Git"

      config syncs the source storage setting to the remote Portal record, and subsequent push calls go through Git.

      With one Portal per repository, the default repository root works fine for --git-path. You only need a subdirectory when you want several Portals in the same repository:

      nb portal config customer --git-path portals/customer

      Pulling from another repository temporarily

      To try out source from another repository without changing the Portal's configuration, pull accepts a one-off override:

      nb portal pull customer --git-repo git@github.com:nocobase/another-portal.git

      This doesn't modify the remote Portal record, and --git-branch and --git-path can only be used together with --git-repo. To switch to Git storage permanently, use config as above.

      config can also change where the dev workspace lives — after moving the source to another directory, tell the CLI its new location with --path:

      nb portal config customer --path ./workspaces/customer

      Differences between env types

      nb portal synchronizes differently depending on the env type:

      env typeDescription
      localThe application is on this machine. pull fetches the source into the dev workspace, deploy builds from the dev workspace and syncs the artifacts
      dockerThe application runs in Docker, shared through a volume. Behavior is the same as above
      httpSynchronized through the API. pull / push download or upload a source archive

      ssh envs don't support Portal management yet.

      Multi-environment deployment

      The same Portal can be deployed to different environments, with --env naming the target:

      nb portal deploy customer --env prod --yes

      --yes skips the interactive confirmation. When the --env you pass explicitly differs from the current env, the CLI stops and asks by default. Remember to include --yes in scripts or CI, otherwise the command hangs at the confirmation.

      For cross-environment collection schema and configuration releases, see Release Management.

      Access path

      Once deployed, a Portal's access path is:

      <appPublicPath>/x/<portal>/

      For a Portal under a sub-application:

      <appPublicPath>/x/apps/<app>/<portal>/

      The /x/ prefix belongs to AI Portals; no-code Portals use /v/.

      Deleting a Portal

      nb portal destroy customer

      This deletes the Portal record and its deployed files, keeping the local dev workspace by default. Add --delete-dev-path when you want the dev workspace gone as well.