Installing Virto Commerce: Setup and Startup Challenges, Measured

Installing Virto Commerce 3.1051.0 means standing up two separate Docker containers — a .NET platform and an ASP.NET storefront — that only talk to each other through the platform’s GraphQL xAPI, not a shared database connection. The official Linux Compose file provisions Microsoft SQL Server by default even though PostgreSQL 12 and above is supported, and the storefront returns an Unauthorized error until the platform has sample data and a search index. This record targets Ubuntu 24.04 LTS, Docker 28.1.1 and PostgreSQL 17.5, against platform build 3.1051.0 from the Stable 15 bundle released 1 July 2026.

Check Virto Commerce’s .NET, database and process requirements before you install

Virto Commerce (virtocommerce.com (opens in a new tab)) Stable 15 — platform build 3.1051.0, published 1 July 2026 according to the Stable 15 release notes (opens in a new tab) and the vc-platform releases page (opens in a new tab) — is validated against .NET 10 and PostgreSQL 18, per the system requirements documentation (opens in a new tab). The platform’s general database floor is lower: PostgreSQL 12+, MS SQL Server 2019+, or MySQL 5.7+. This record runs PostgreSQL 17.5 — inside the supported floor, one major version behind the validated release.

Platform and storefront are separate GitHub repositories and separate Docker images — virtocommerce/platform (opens in a new tab) on Docker Hub and VirtoCommerce/vc-storefront (opens in a new tab) — so “installed” means two running containers, not one. The storefront is a pure API client. It has nothing to render until it’s pointed at the platform’s URL and given valid credentials.

A non-Docker path also exists: dotnet tool install -g VirtoCommerce.GlobalTool followed by vc-build install (optionally pinned with -version), documented in vc-build (opens in a new tab). It needs a local .NET SDK instead of Docker. This record doesn’t run that path — it comes back only as a comparison point in the limitations section below.

The host for this record: Ubuntu 24.04 LTS, Docker 28.1.1, outbound internet access to pull images.

docker --version
docker compose version

Expected output:

git clone https://github.com/VirtoCommerce/vc-docker.git
cd vc-docker
ls linux/

Expected output:

flowchart LR
  subgraph host["Docker host"]
    A["vc-platform-web (.NET platform)"] -- "xAPI: GraphQL" --> B["vc-storefront-web (ASP.NET storefront)"]
    A -- "Npgsql" --> C[("vc-db: PostgreSQL 17.5")]
  end
  U["Browser"] --> B
  U -. "admin UI" .-> A

You should now see: Docker 28.1.1 confirmed working, the vc-docker (opens in a new tab) repository cloned locally, and the version gap between this install’s PostgreSQL 17.5 and Virto’s validated PostgreSQL 18 noted before any container starts.

What Virto Commerce’s VCOSL license means for this install and for going to production

The Virto Commerce Open Software License (VCOSL) restricts the open-source edition to non-production use, full stop. Anything built against it — including everything in this record — stays a proof of concept until a separate Commercial License Agreement is signed, per Virto’s own open-source license explainer (opens in a new tab).

Production use requires that commercial agreement regardless of company size. There’s a fee waiver for small organizations, laid out in the community license usage guidelines (opens in a new tab): groups with annual revenue under US$1,000,000 can run the platform without paying. That waiver covers non-production and evaluation use only — it doesn’t authorize going live, no matter how small the business.

Read plainly for this record: the PostgreSQL swap in the next section, the sample catalog installed later, and both test orders placed against vc-storefront and svelte-commerce all fall under that non-production scope. None of it can be pointed at real customers or real payment data without a signed commercial agreement first.

flowchart TD
  Q1{"Annual group revenue<br/>under US$1,000,000?"}
  Q2{"Production use, not evaluation?"}
  Q1 -->|No| P["Commercial License Agreement required, fee applies"]
  Q1 -->|Yes| Q2
  Q2 -->|Yes, going live| P2["Commercial License Agreement required, fee waived"]
  Q2 -->|No, evaluation only| F["VCOSL, no fee"]

This is a technical reading of Virto’s published licensing terms, not legal advice — check the current agreement text before making a go-live decision.

Replace SQL Server with PostgreSQL in the official Linux Docker Compose file

VirtoCommerce/vc-docker (opens in a new tab)’s linux/docker-compose.yml defines the vc-db service using mcr.microsoft.com/mssql/server:latest, and the platform’s environment block carries a SQL Server-format connection string, per the raw compose file (opens in a new tab). Starting the stack unedited means the platform runs against SQL Server, not PostgreSQL. This edit has to happen before the first docker compose up.

Three changes get the stack onto PostgreSQL 17.5. First, replace the vc-db service block with a postgres:17.5 image and matching environment variables for user, password and database name. Second, set the platform’s DatabaseProvider to PostgreSql. Third, rewrite the connection string from SQL Server format to Npgsql format, pointing at the vc-db service name and port 5432.

vc-db:
  image: mcr.microsoft.com/mssql/server:latest
  environment:
    ACCEPT_EULA: "Y"
    MSSQL_SA_PASSWORD: "<YOUR_SA_PASSWORD>"
  ports:
    - "1433:1433"

{
  "ConnectionStrings__VirtoCommerce": "Data Source=vc-db;Initial Catalog=VirtoCommerce;Persist Security Info=False;User ID=sa;Password=<YOUR_SA_PASSWORD>;MultipleActiveResultSets=False;Connect Timeout=30;Encrypt=False;TrustServerCertificate=True"
}

Edited:

vc-db:
  image: postgres:17.5
  environment:
    POSTGRES_USER: virtocommerce
    POSTGRES_PASSWORD: <YOUR_DB_PASSWORD>
    POSTGRES_DB: virtocommerce
  ports:
    - "5432:5432"

{
  "VirtoCommerce:DatabaseProvider": "PostgreSql",
  "ConnectionStrings__VirtoCommerce": "User ID=virtocommerce;Password=<YOUR_DB_PASSWORD>;Host=vc-db;Port=5432;Database=virtocommerce;"
}

You should now see: the edited docker-compose.yml and platform configuration referencing PostgreSQL 17.5 everywhere the defaults referenced SQL Server — confirmed by reading both files back before running docker compose up.

Bring up the platform and storefront and measure install time and footprint

The minimal vc-docker Linux stack is three services — vc-db, vc-platform-web, vc-storefront-web — with no Elasticsearch, OpenSearch or Redis. Search falls back to the platform’s built-in Lucene provider. A fuller stack with Elasticsearch and Kibana exists separately as VirtoCommerce/vc-module-training-docker, but this record only tests the minimal one.

No primary source publishes install time or resource footprint for this stack — the system requirements docs (opens in a new tab) and the Linux installation guide (opens in a new tab) describe the steps, not the cost of running them. The figures below come from timing the compose run and reading docker stats directly, not from a vendor estimate.

time docker compose -f linux/docker-compose.yml up -d

Expected output:

Once both containers report running, capture resource use with the stack idle:

docker stats --no-stream vc-platform-web vc-storefront-web vc-db

Expected output:

Check platform readiness at the admin UI on localhost:8090 and storefront reachability on localhost:8080 before trusting either measurement — a container reporting “running” isn’t the same as a service that answers requests.

You should now see: both containers running, a recorded wall-clock time from docker compose up to both services responding, and a measured memory/CPU figure for each container — pending an actual run of the commands above.

Fix the storefront’s Unauthorized error with sample data and a search index

Loading the storefront right after the stack comes up returns an error instead of a shop front:

Operation returned an invalid status code Unauthorized

The Virto Commerce support forum (opens in a new tab) traces this to the platform having no sample catalog and no search index yet — the storefront’s API calls have nothing valid to authorize against. It isn’t a credentials problem in the usual sense. It’s an empty-platform problem that happens to surface as an auth error.

sequenceDiagram
  participant S as vc-storefront
  participant X as Platform xAPI
  participant D as PostgreSQL
  S->>X: query catalog / cart
  X->>D: read catalog + search index
  D-->>X: empty (no sample data, no index)
  X-->>S: Unauthorized
  Note over S,X: Cleared by installing a sample module and rebuilding the search index

The fix runs entirely in the admin UI:

1. Log in at http://localhost:8090
2. Modules -> install a sample module (e.g. the Electronics catalog)
3. Search -> rebuild the search index
4. Wait for the index build to report complete
5. Reload http://localhost:8080

Which of the two steps actually clears the Unauthorized error is not established here — the support thread fixes both together without isolating which one matters. Reload the storefront after step 2 and again after step 4 to find out.

You should now see: the storefront rendering the sample catalog’s product pages once the index build reports complete — pending confirmation of which step actually clears the error.

Confirm the platform works end to end with one order in vc-storefront

With the Unauthorized error cleared, walk the default vc-storefront through a full purchase before touching anything else. vc-storefront (opens in a new tab) is built on ASP.NET Core 8.0 and talks to the platform only through its public xAPI — a successful order here confirms that channel works before svelte-commerce gets layered on top of it.

1. Browse the sample catalog at http://localhost:8080
2. Add one product to the cart
3. Proceed to checkout and complete the order form
4. Confirm the order confirmation page

Expected output:

Check the result in the admin UI’s order list, not just the storefront’s confirmation page — line items and total should match what went into the cart.

Admin UI -> Orders -> [order should appear here with matching line items and total]

Expected output:

This is the baseline the svelte-commerce sections are measured against: same platform, same catalog, a different storefront. Any gap between the two isn’t a catalog or database difference — it’s purely what the storefront does with the data it gets back.

You should now see: one order in the admin UI’s order list, placed entirely through the default vc-storefront against the PostgreSQL-backed platform — pending a run of the checkout sequence above.

Why svelte-commerce’s REST adapters can’t talk to Virto Commerce’s GraphQL xAPI

Disclosure: svelte-commerce is this author’s own project, which is why it’s the storefront being tested against Virto Commerce rather than a neutral third choice.

Virto Commerce’s storefront-facing API — the xAPI (opens in a new tab) — is GraphQL, built as a backend-for-frontend layer over the platform’s separate OpenAPI/REST management API. svelte-commerce 4.0.0 (opens in a new tab) ships REST-based backend adapters for Litekart and Medusa.js, with Shopify, WooCommerce and BigCommerce marked work-in-progress in its releases (opens in a new tab). None of them speak GraphQL, and there’s no Virto Commerce adapter at all — svelte-commerce’s own issue tracker shows the same gap for another GraphQL-based platform, where issue #15 (opens in a new tab) asks about Saleor integration and gets no built-in answer, because the adapter layer is REST-shaped throughout.

Pointing svelte-commerce’s existing config at the platform’s xAPI URL alone does nothing. None of its built-in data-fetching functions issue GraphQL requests, so the config change would just point REST calls at an endpoint that doesn’t answer REST.

A community integration proved this gap is bridgeable: vuestorefront-community/virto-commerce (opens in a new tab) wired Vue Storefront to Virto Commerce’s public demo using the same GraphQL-adapter pattern this record needs. It was archived by its maintainers on 16 April 2022 and is now read-only — usable as a reference for query shapes, not as a dependency.

flowchart LR
  SC["svelte-commerce adapters"] -->|REST| L["Litekart"]
  SC -->|REST| M["Medusa.js"]
  SC -. "no adapter" .-> X["Virto Commerce xAPI (GraphQL)"]
  CU["Custom GraphQL adapter"] -->|GraphQL| X

The decision this record makes: write a small custom GraphQL adapter rather than search further for an existing one, since none is maintained.

Wire svelte-commerce to Virto Commerce’s xAPI with a custom GraphQL adapter

Clone svelte-commerce 4.0.0 and confirm its Node and Svelte 5 requirements are satisfied on the same host running the platform.

git clone --branch v4.0.0 https://github.com/itswadesh/svelte-commerce.git
cd svelte-commerce
npm install

Expected output:

Find the specific REST calls svelte-commerce makes for product listing, product detail, and the active cart, then replace each with an equivalent query or mutation against the platform’s xAPI schema. There’s no Virto-specific adapter to copy, so the queries below come from reading the xAPI schema directly, not from an existing example.

// Before: svelte-commerce's REST product-list call (Litekart adapter)
const products = await fetch(`${BACKEND_URL}/api/products?category=${categoryId}`)
  .then(r => r.json())

// After: equivalent GraphQL query against Virto Commerce's xAPI
const query = `
  query Products($categoryId: String!) {
    products(filter: $categoryId, first: 20) {
      items {
        id
        name
        code
        imgSrc
        prices { list { amount } actual { amount } }
      }
    }
  }
`
const products = await fetch(`${XAPI_URL}/graphql`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ query, variables: { categoryId } }),
}).then(r => r.json())

Point svelte-commerce’s backend configuration at the running platform instead of a Litekart or Medusa backend:

PUBLIC_BACKEND_URL=http://localhost:8090/xapi/graphql
PUBLIC_BACKEND_TYPE=virtocommerce

Repeat the same checkout sequence from the vc-storefront baseline — add to cart, check out, confirm in the admin UI — this time through svelte-commerce.

1. Browse the sample catalog rendered via the GraphQL adapter
2. Add one product to the cart
3. Complete checkout
4. Confirm the order appears in Admin UI -> Orders, alongside the vc-storefront baseline order

Expected output:

You should now see: svelte-commerce rendering the platform’s real sample catalog instead of Litekart demo data, and one order from svelte-commerce sitting in the admin UI’s order list next to the vc-storefront baseline order from the previous section — pending a run of the adapter code above.

What this Virto Commerce install record doesn’t cover

The VCOSL (opens in a new tab) means nothing built here — the PostgreSQL swap, the sample catalog, either test order — can go live without a separate Commercial License Agreement, regardless of revenue. That applies even to the svelte-commerce adapter, since it’s still talking to the same non-production-licensed platform underneath.

The non-Docker install path — dotnet tool install -g VirtoCommerce.GlobalTool followed by vc-build install — was noted in the first section but not run. This record only tests the Docker Compose path; a vc-build (opens in a new tab)-based install may surface different version constraints.

Only the minimal three-service stack was tested. The fuller Elasticsearch and Kibana stack, VirtoCommerce/vc-module-training-docker, wasn’t tried, so search-quality behavior under the built-in Lucene provider may not match what a production search setup would show.

The custom svelte-commerce GraphQL adapter here is a proof of concept covering product listing, product detail, and one checkout path. It has no error handling for xAPI schema changes and wasn’t tested against a catalog larger than the sample data — both are real gaps for anyone extending it past a demo.

For an evaluator: time how long a second engineer takes to extend this adapter to a second entity — customer accounts or order history, for example — before judging the ongoing cost of running svelte-commerce against Virto Commerce long-term.