7.configuration.md

title	layout
Configuration	default

Deployment - Configuration

Deploying your Alokai stores is incredibly simple! With our powerful deployment system, you can go from development to production in just a few minutes.

A single CLI command takes care of everything – it builds the store, optimizes it for deployment, creates a Docker image, pushes it to our repository, and initiates the deployment process on the cluster.

Whether you’re managing a single store or orchestrating multiple brands, Alokai’s configuration system makes deployment effortless. This guide will show you how to leverage these capabilities and get your stores up and running with minimal effort.

What You'll Learn

::list{type="success"}

• Configuring your alokai.config.json for successful deployments
• Choosing and configuring frameworks for your stores
• Managing multiple store deployments efficiently
• Running and testing deployments locally ::

Core Concepts

The alokai.config.json File

The alokai.config.json file is the central configuration file that controls how your stores are deployed. It contains essential settings for:

• Project identification
• Deployment regions
• Framework selection
• Store-specific configurations

Example configuration:

{
  "stores": {
    "fashion-brand": {
      "deployment": {
        "projectName": "fashion-brand-prod",
        "region": "us-east-1",
        "framework": "nextjs"
      }
    },
    "sports-brand": {
      "deployment": {
        "projectName": "sports-brand-prod",
        "region": "eu-west-1",
        "framework": "nuxt"
      }
    }
  }
}

::warning Configuration Required Each deployable store must have a valid configuration in alokai.config.json. Template stores shouldn't be placed in the alokai.config.json file as they are not deployed. ::

Configuration Parameters

projectName

The projectName parameter is a crucial identifier that links your store to Alokai Console.

::tip Finding Your Project Name You can find your project name in the Deployment Variables section of the Alokai Console. ::

Example configuration:

{
  "stores": {
    "fashion-brand": {
      "deployment": {
        "projectName": "fashion-brand-prod",  // Must match Alokai Console project name
        // ... other parameters
      }
    }
  }
}

region

The region parameter determines where your store will be deployed.

::warning region Required Deployment cannot be triggered without a valid region configuration. The region value can be found in the Deployment Variables section of the Alokai Console. Ensure the value in alokai.config.json matches the region selected for your project. ::

Example region configuration:

{
  "stores": {
    "fashion-brand": {
      "deployment": {
        "region": "us-east-1",  // AWS region identifier
        // ... other parameters
      }
    }
  }
}

framework

::info Auto-detection The framework parameter is optional when your project uses only one frontend framework (Next.js or Nuxt). In this case, Alokai CLI will automatically detect and use the correct framework. ::

The framework parameter defines whether a store uses Next.js or Nuxt. Alokai supports both frameworks out of the box through two base applications:

• apps/storefront-unified-nextjs for Next.js stores
• apps/storefront-unified-nuxt for Nuxt stores

Each store in alokai.config.json may specify which framework it will use for deployment:

{
  "stores": {
    "fashion-brand": {
      "deployment": {
        "framework": "nextjs",  // This store will deploy using Next.js
        // ... other parameters
      }
    },
    "sports-brand": {
      "deployment": {
        "framework": "nuxt",  // This store will deploy using Nuxt
        // ... other parameters
      }
    }
  }
}

Your project structure can support both frameworks simultaneously. For example:

apps/
├── storefront-unified-nextjs/     # Base Next.js implementation
├── storefront-unified-nuxt/       # Base Nuxt implementation
└── stores/
    ├── fashion-brand/            
    │   ├── storefront-unified-nextjs/  # Next.js Storefront
    └── sports-brand/
        └── storefront-unified-nuxt/    # Nuxt Storefront

This dual-framework support is particularly beneficial when:

• Different teams specialize in different frameworks
• You're migrating from one framework to another
• Specific stores have requirements better suited to a particular framework

Local Build & Deployment via CLI

::warning Development Environment Only Triggering deployments locally should only be used for development and testing purposes. For production deployments, we recommend using CI/CD pipelines (like GitHub Actions, GitLab CI, or Bitbucket Pipelines) as they provide better credentials' security, a controlled deployment environment, version control integration, and automated validation checks. You can read more about it in the CI/CD guide. ::

Prerequisites

1. Docker

   • Docker must be installed and running on your machine

2. Cloud Credentials

   • Find your credentials in the Alokai Console
   • Use staging/dev environment for triggering deployments locally
   • Set up environment variables or provide them via CLI flags:
     • CLI_CLOUD_USERNAME or --cloud-username
     • CLI_CLOUD_PASSWORD or --cloud-password

3. Docker Registry

   • Default registry: registry.vuestorefront.cloud
   • Can be customized using --docker-registry-url flag or CLI_DOCKER_REGISTRY_URL environment variable

4. Configuration Verification

   • Double-check alokai.config.json configuration
   • Verify projectName matches intended deployment target
   • Confirm region selection is appropriate for testing

Deployment Command

One of the great things about Alokai is how simple it makes deployments! The basic deployment command is:

yarn alokai store deploy --store-id=fashion-brand \
  --cloud-username=your_username \
  --cloud-password=your_password

::tip Environment Variables You can simplify the command by using environment variables. The Alokai CLI automatically loads variables from the .env file in your project root, which is the recommended approach:

# .env file in your project root
CLI_CLOUD_USERNAME=your_username
CLI_CLOUD_PASSWORD=your_password

Alternatively, you can set them manually in your terminal:

export CLI_CLOUD_USERNAME=your_username
export CLI_CLOUD_PASSWORD=your_password

With either approach, you'll only need to specify the store-id:

yarn alokai store deploy --store-id=fashion-brand

::

That's it! The CLI handles all the complexity of building, packaging, and deploying your store. You can also add --verbose flag to see detailed logs:

yarn alokai store deploy --store-id=fashion-brand \
  --verbose  # Optional: see detailed deployment logs

You can also use the --all flag to deploy all deployable stores.

::tip Easy Development The ability to deploy locally makes development and testing much faster! You can quickly test your changes in a production-like environment without waiting for CI/CD pipelines. If you want to deploy to a different project in console, you can temporarily change the projectName in alokai.config.json. ::

::danger Credential Security For security reasons, you must never commit credentials to version control, share credentials with unauthorized team members or use production credentials for triggering deployments locally. Always prefer using environment variables. ::

::card{title="Next: Deployment - CI/CD" icon="tabler:number-3-small" }

#description Learn how to set up automated deployments using CI/CD pipelines, ensuring consistent and reliable deployments across your stores.

#cta :::docs-arrow-link{to="/guides/multistore/tooling-and-concepts/cd"} Next ::: ::