Hosting your
Cartex system.

A home for your store.

You'll need a server with Docker and Docker Compose, a domain for your storefront, and access to the Cartex container image. Technical familiarity with hosting, environment variables, and databases is recommended.

• PostgreSQL, either bundled with Compose or hosted externally.
• Ziqx Auth credentials for authentication.
• Ziqx Drive credentials and a public media root for uploaded files.
• An SMTP provider for email.
• A payment provider account and your shipping configuration.
• A reverse proxy configured with HTTPS for production.

Provider services and infrastructure may have their own costs. Confirm your account access and configuration before launching.

Bring the essentials together.

Create a .env file beside your Compose file. Replace the placeholders with your own values and keep this file out of source control. Use a strong URL-safe database password for this example.

POSTGRES_PASSWORD=replace-with-a-strong-url-safe-password
ZAUTH_SECRET=your-auth-secret
ZDRIVE_KEY=your-drive-key
ZDRIVE_SECRET=your-drive-secret
JWT_SECRET=your-jwt-secret
APP_CONFIG_ENCRYPTION_KEY=your-encryption-key
SMTP_HOST=your-smtp-host
SMTP_USER=your-smtp-user
SMTP_PASSWORD=your-smtp-password
CRON_SECRET=your-cron-secret
ADMIN_EMAILS=you@example.com
NEXT_PUBLIC_URL=https://shop.example.com
NEXT_PUBLIC_ZAUTH_KEY=your-public-auth-key
NEXT_PUBLIC_ZDRIVE_ROOT=your-public-media-root

The NEXT_PUBLIC_ values are browser-visible. Keep private credentials in the server-side variables. Refer to the application's env.example for the full configuration and credential format requirements.

Your store starts here.

Pull the image, then save the configuration below as docker-compose.yml. If the registry requires authentication, sign in with your authorized GitHub Container Registry credentials first.

services:
  postgres:
    image: postgres:17-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: cartex
      POSTGRES_USER: cartex
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U cartex -d cartex"]
      interval: 10s
      timeout: 5s
      retries: 5
  cartex:
    image: ghcr.io/fathah/cartex-pro:latest
    restart: unless-stopped
    ports:
      - "3003:3000"
    env_file: .env
    environment:
      DATABASE_URL: postgresql://cartex:${POSTGRES_PASSWORD}@postgres:5432/cartex
      RUN_DATABASE_MIGRATIONS: "true"
    depends_on:
      postgres:
        condition: service_healthy
volumes:
  postgres_data:

This example runs migrations on container startup and saves your database in a persistent volume. Start the services:

docker compose up -d

Open http://localhost:3003/setup on the host, or route your domain to port 3003 through your HTTPS reverse proxy. Complete the setup wizard. For a managed database, replace DATABASE_URL with your provider's connection string and remove the bundled database service and its dependency.

Start small. Test the whole journey.

1. Confirm your store name, logo, default currency, and tax settings.
2. Activate your first market in Settings → Market Country.
3. Configure a payment gateway and customer-facing payment method.
4. Add a warehouse and configure delivery options.
5. Create a category and an active test product.
6. Place a test order. Verify payment, tax, shipping, stock, notifications, and fulfillment.

Configure your provider webhooks and scheduled payment reconciliation and inventory-reservation jobs using the application documentation. Review each new market's checkout before opening it to customers.

Once deployed, your store's /admin/docs includes guides for day-to-day operations, catalog management, payments, shipping, returns, and more.

Room for the next chapter.

Back up your database regularly. Review and test updates before rolling them out to your live store.

docker compose pull
docker compose up -d

After environment changes, recreate the app container with docker compose up -d --force-recreate. With multiple app instances, run migrations once before scaling out.