Unchained Engine

Sign in to the Azure Portal. Choose Create a resource, search the Marketplace for Unchained Engine by SecureAnyCloud, and select Create.

On Basics, pick your subscription, resource group, region and size. Under Administrator account, choose SSH public key and paste your key. Under Inbound port rules, allow SSH (22) and HTTP (80).

Then select Review + create and Create.

RG="unchained-prod"; LOCATION="eastus"; VM_NAME="unchained-01" IMAGE_URN="sac1647283583153:unchained-ubuntu-24-04:default:latest" SSH_KEY="$(cat ~/.ssh/id_rsa.pub)" az group create --name "$RG" --location "$LOCATION" az network vnet create -g "$RG" --name unchained-vnet --address-prefix 10.100.0.0/16 --subnet-name unchained-subnet --subnet-prefix 10.100.1.0/24 az network nsg create -g "$RG" --name unchained-nsg az network nsg rule create -g "$RG" --nsg-name unchained-nsg --name allow-ssh --priority 100 \
  --source-address-prefixes "<your-mgmt-cidr>" --destination-port-ranges 22 --access Allow --protocol Tcp az network nsg rule create -g "$RG" --nsg-name unchained-nsg --name allow-http --priority 110 \
  --destination-port-ranges 80 --access Allow --protocol Tcp
# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:unchained-ubuntu-24-04:default:latest
az vm create -g "$RG" --name "$VM_NAME" --image "$IMAGE_URN" \
  --size Standard_B2s --storage-sku StandardSSD_LRS \
  --admin-username azureuser --ssh-key-values "$SSH_KEY" \
  --vnet-name unchained-vnet --subnet unchained-subnet --nsg unchained-nsg --public-ip-sku Standard

Connect over SSH as azureuser, then confirm all four units are active. unchained-firstboot.service is a one-shot unit that reports active once it has completed successfully.

systemctl is-active mongod nginx unchained unchained-firstboot

Expected output:

active active active active

Check the engine release that is actually installed, its licence, and that both the console and the API answer:

node -p "'Unchained Engine ' + require('/opt/unchained/node_modules/@unchainedshop/platform/package.json').version + ' (licence ' + require('/opt/unchained/node_modules/@unchainedshop/platform/package.json').license + ')'"
node --version mongod --version | head -1 curl -s -o /dev/null -w 'Unchained admin console: HTTP %{http_code}\n' http://127.0.0.1/ curl -s -o /dev/null -w 'Unchained GraphQL API: HTTP %{http_code}\n' -X POST http://127.0.0.1/graphql \
  -H 'content-type: application/json' --data '{"query":"{shopInfo{version}}"}'

Expected output:

Unchained Engine 4.8.25 (licence EUPL-1.2) v22.23.2 db version v8.0.31 Unchained admin console: HTTP 200 Unchained GraphQL API: HTTP 200

Every secret on this VM was generated on its first boot and exists nowhere else. They are written to a root-only file.

sudo stat -c '%n mode=%a owner=%U:%G' /root/unchained-credentials.txt
sudo grep -o '^[a-z.]*=' /root/unchained-credentials.txt | tr -d '='

Expected output:

/root/unchained-credentials.txt mode=600 owner=root:root unchained.url unchained.graphql unchained.admin.username unchained.admin.email unchained.admin.password mongo.admin.username mongo.admin.password mongo.app.username mongo.app.password mongo.database

Read the values when you need them, with sudo cat /root/unchained-credentials.txt. Copy the administrator username and password into your password manager now, then continue.

Browse to http://<your-vm-public-ip>/. Signing in takes two steps: enter the unchained.admin.username value, choose Continue, then enter the unchained.admin.password value.

You can prove the same credential works from the command line before you open a browser. This reads the generated password straight from the credentials file, so there is nothing to paste:

JAR="$(mktemp)" ADMIN_USER="$(sudo grep '^unchained.admin.username=' /root/unchained-credentials.txt | cut -d= -f2-)" ADMIN_PASS="$(sudo grep '^unchained.admin.password=' /root/unchained-credentials.txt | cut -d= -f2-)" curl -s -c "$JAR" -X POST http://127.0.0.1/graphql -H 'content-type: application/json' \
  --data "{\"query\":\"mutation{loginWithPassword(username:\\\"${ADMIN_USER}\\\",password:\\\"${ADMIN_PASS}\\\"){_id}}\"}" > /dev/null curl -s -b "$JAR" -X POST http://127.0.0.1/graphql -H 'content-type: application/json' \
  --data '{"query":"{me{username roles}}"}' echo rm -f "$JAR"

Expected output:

{"data":{"me":{"username":"admin","roles":["admin"]}}}

Once signed in you land on the dashboard, which confirms the shop is configured and summarises the catalogue, customers, sales and orders.

Your VM starts with an empty catalogue. Add a product from Products in the console sidebar, choose Add Product, pick a product type and give it a title, then set a price under the product's Commerce tab and publish it.

The same thing over the API. This signs in, creates a product with an English title and a price, publishes it, reads it back, and then removes it again so your catalogue is left exactly as it was:

JAR="$(mktemp)" ADMIN_USER="$(sudo grep '^unchained.admin.username=' /root/unchained-credentials.txt | cut -d= -f2-)" ADMIN_PASS="$(sudo grep '^unchained.admin.password=' /root/unchained-credentials.txt | cut -d= -f2-)" gql() { curl -s -c "$JAR" -b "$JAR" -X POST http://127.0.0.1/graphql -H 'content-type: application/json' --data "$1"; } gql "{\"query\":\"mutation{loginWithPassword(username:\\\"${ADMIN_USER}\\\",password:\\\"${ADMIN_PASS}\\\"){_id}}\"}" > /dev/null PRODUCT_ID="$(gql '{"query":"mutation($p:CreateProductInput!,$t:[ProductTextInput!]){createProduct(product:$p,texts:$t){_id}}","variables":{"p":{"type":"SIMPLE_PRODUCT","tags":["guide-example"]},"t":[{"locale":"en","title":"Guide example product","slug":"guide-example-product"}]}}' | sed -n 's/.*"_id":"\([^"]*\)".*/\1/p')" gql "{\"query\":\"mutation{updateProductCommerce(productId:\\\"${PRODUCT_ID}\\\",commerce:{pricing:[{amount:2500,currencyCode:\\\"USD\\\",countryCode:\\\"US\\\",isTaxable:true,isNetPrice:false}]}){_id}}\"}" > /dev/null gql "{\"query\":\"mutation{publishProduct(productId:\\\"${PRODUCT_ID}\\\"){_id}}\"}" > /dev/null gql "{\"query\":\"{product(productId:\\\"${PRODUCT_ID}\\\"){status texts{title} ... on SimpleProduct{simulatedPrice{amount currencyCode}}}}\"}" echo gql "{\"query\":\"mutation{removeProduct(productId:\\\"${PRODUCT_ID}\\\"){_id}}\"}" > /dev/null rm -f "$JAR"

Expected output:

{"data":{"product":{"status":"ACTIVE","texts":{"title":"Guide example product"},"simulatedPrice":{"amount":2500,"currencyCode":"USD"}}}}

Product is a GraphQL interface, so the price lives on the concrete type: the inline fragment ... on SimpleProduct is what reaches it. Prices are held in minor units, so 2500 is $25.00.

Orders placed by your storefront, mobile app or any other client appear under Orders, with the order number, date, computed total, customer and status. From an order you can inspect its items, delivery and payment, and move it through the fulfilment lifecycle.

Everything the console does here is available over the API, which is how your own storefront drives it. A cart is created by adding a product, then given a contact and billing address and a delivery and payment provider, then checked out:

JAR="$(mktemp)" ADMIN_USER="$(sudo grep '^unchained.admin.username=' /root/unchained-credentials.txt | cut -d= -f2-)" ADMIN_PASS="$(sudo grep '^unchained.admin.password=' /root/unchained-credentials.txt | cut -d= -f2-)" gql() { curl -s -c "$JAR" -b "$JAR" -X POST http://127.0.0.1/graphql -H 'content-type: application/json' --data "$1"; } gql "{\"query\":\"mutation{loginWithPassword(username:\\\"${ADMIN_USER}\\\",password:\\\"${ADMIN_PASS}\\\"){_id}}\"}" > /dev/null gql '{"query":"{deliveryProviders{_id type}paymentProviders{_id type}}"}' echo rm -f "$JAR"

Expected output (your identifiers will differ):

{"data":{"deliveryProviders":[{"_id":"027340fe3023d629d1bda2d1","type":"SHIPPING"}],"paymentProviders":[{"_id":"bc8eb70f383b2db30274fc05","type":"INVOICE"}]}}

Those two providers are created for you on first boot, so the engine can price and accept an order out of the box. The full cart and checkout flow is addCartProduct, then updateCart with a contact, billing address and those two provider identifiers, then checkoutCart.

Four properties are worth verifying yourself.

JAR="$(mktemp)" ADMIN_USER="$(sudo grep '^unchained.admin.username=' /root/unchained-credentials.txt | cut -d= -f2-)" ADMIN_PASS="$(sudo grep '^unchained.admin.password=' /root/unchained-credentials.txt | cut -d= -f2-)" curl -s -c "$JAR" -X POST http://127.0.0.1/graphql -H 'content-type: application/json' \
  --data "{\"query\":\"mutation{loginWithPassword(username:\\\"${ADMIN_USER}\\\",password:\\\"${ADMIN_PASS}\\\"){_id}}\"}" > /dev/null curl -s -b "$JAR" -X POST http://127.0.0.1/graphql -H 'content-type: application/json' \
  --data '{"query":"{usersCount}"}' | sed 's/.*"usersCount":\([0-9]*\).*/accounts on this VM: \1/' rm -f "$JAR" for P in password admin; do printf 'upstream default admin/%s -> ' "$P" curl -s -X POST http://127.0.0.1/graphql -H 'content-type: application/json' \
  --data "{\"query\":\"mutation{loginWithPassword(username:\\\"admin\\\",password:\\\"${P}\\\"){_id}}\"}" \
  | grep -qo '"_id"' && echo 'ACCEPTED' || echo 'refused' done curl -s -X POST http://127.0.0.1/graphql -H 'content-type: application/json' \
  --data '{"query":"mutation{createProduct(product:{type:SIMPLE_PRODUCT}){_id}}"}' \
  | python3 -c "import json,sys; print('anonymous createProduct -> ' + (json.load(sys.stdin).get('errors') or [{}])[0].get('message','ALLOWED'))" ss -tlnH | awk '{print $4}' | grep -E ':(80|4010|27017)$' | sort -u | sed 's/^/listening on /'

Expected output:

accounts on this VM: 1 upstream default admin/password -> refused upstream default admin/admin -> refused anonymous createProduct -> The user "anonymous" has no permission to perform the action "manageProducts" in "createProduct" listening on 0.0.0.0:80 listening on 127.0.0.1:27017 listening on 127.0.0.1:4010 listening on [::]:80

• One account, no default. Every upstream example application creates admin with the password password and commits the signing secrets alongside it. Those values do not exist in this image, and the build fails closed if any of them ever reaches the shipped configuration. Your VM's single administrator was created on first boot with a random password.
• The engine and the database are private. The engine listens on 127.0.0.1:4010 and MongoDB on 127.0.0.1:27017. Only nginx on port 80 is reachable from the network.
• Administrative operations are role-gated. The commerce API is deliberately reachable, because that is what a headless engine is for and it is how your storefront talks to it. Everything administrative is refused to anyone without the role for it, as the anonymous createProduct above shows.
• Customer sign-up is open by design. The console's sign-in page offers a Sign up link, and the API exposes account creation, because a shop needs customers to be able to register. New accounts get no administrative rights whatsoever. If you do not want public registration, restrict access to port 80 with a network security group as described in Step 9, or put your own storefront in front of the API and expose only that.

The image serves plain HTTP on port 80 so it works immediately at any address. For anything beyond a trial, terminate TLS with your own certificate and restrict access with a network security group.

Point a DNS A record at the VM's public IP, allow 443/tcp in the NSG, then install a certificate. Replace the values in angle brackets with your own:

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d <your-domain> -m <your-email> --agree-tos --redirect

Because the admin console calls the API on the same origin using relative paths, no rebuild or reconfiguration is needed when you move to a hostname or to HTTPS. It simply works at the new address.

Once you are serving over HTTPS, tighten the session cookie. The image ships a cookie that a browser will accept over plain HTTP, which necessarily means it is not marked Secure. Edit /opt/unchained/.env, remove the UNCHAINED_COOKIE_INSECURE=1 line, and restart the engine:

sudo sed -i '/^UNCHAINED_COOKIE_INSECURE=1$/d' /opt/unchained/.env
sudo systemctl restart unchained

Also update ROOT_URL and EMAIL_WEBSITE_URL in the same file to your https:// address so any absolute links the engine generates point at your domain.

The engine queues order confirmations, password resets and account messages onto its work queue and hands them to an SMTP server. No SMTP server is configured out of the box, so those work items fail until you set one. Add your SMTP URL to /opt/unchained/.env and restart:

sudo sed -i 's|^MAIL_URL=.*|MAIL_URL=smtps://user:pass@smtp.example.com:465|' /opt/unchained/.env
sudo systemctl restart unchained

Until you do, the console's dashboard may show a Problems detected in the Work Queue banner counting failed EMAIL items. That is the expected state of an engine with no mail server attached, not a fault with the image. Review or retry the items under Work queue in the console sidebar.

All shop data lives in the unchained MongoDB database. Take a dump with the application credentials from the credentials file:

MONGO_APP_PASSWORD="$(sudo grep '^mongo.app.password=' /root/unchained-credentials.txt | cut -d= -f2-)" sudo mkdir -p /var/backups/unchained
sudo mongodump --host 127.0.0.1 --port 27017 \
  -u unchained -p "${MONGO_APP_PASSWORD}" --authenticationDatabase unchained \
  --db unchained --out /var/backups/unchained/$(date -u +%Y%m%d)

Uploaded media is stored inside MongoDB by the GridFS file adapter, so the dump above covers it. To restore, use mongorestore with the same credentials.

MongoDB is deliberately not reachable from the network. To use a graphical client from your workstation, forward the port over SSH:

ssh -N -L 27017:127.0.0.1:27017 azureuser@<vm-ip>

Then connect to mongodb://127.0.0.1:27017 using the mongo.admin.username and mongo.admin.password values from the credentials file, with admin as the authentication database.