Skip to content

Commit ba3168e

Browse files
krystian-panek-vmltechkrystian-panek-vmltech
committed
Doc
1 parent bdc33a5 commit ba3168e

1 file changed

Lines changed: 202 additions & 4 deletions

File tree

‎README.md‎

Lines changed: 202 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,17 @@ Its seamless integration with Terraform, Pulumi, and Ansible enhances automation
5959
- [Installing packages with troubleshooting](#installing-packages-with-troubleshooting)
6060
- [Concepts](#concepts)
6161
- [Local vs Remote Instances](#local-vs-remote-instances)
62+
- [Instance ID Naming Convention](#instance-id-naming-convention)
63+
- [Example Instance IDs](#example-instance-ids)
64+
- [Using Instance IDs](#using-instance-ids)
6265
- [Examples](#examples)
66+
- [Managing Local Instances](#managing-local-instances)
67+
- [Deploying Packages](#deploying-packages)
68+
- [OSGi Configuration](#osgi-configuration)
69+
- [Repository Operations](#repository-operations)
70+
- [Instance Backups](#instance-backups)
71+
- [Basic Commands](#basic-commands)
72+
- [Backup \& Restore Cycle](#backup--restore-cycle)
6373
- [Replication agents](#replication-agents)
6474
- [SSL by Default](#ssl-by-default)
6575
- [Global Trust Store](#global-trust-store)
@@ -672,27 +682,216 @@ When configuring instances, AEMC automatically determines the type based on the
672682
- URLs with `localhost` or `127.0.0.1` → treated as **local**
673683
- Other URLs → treated as **remote**
674684

685+
## Instance ID Naming Convention
686+
687+
Each instance has a unique ID following the pattern: **`{location}_{role}[_{classifier}]`**
688+
689+
| Component | Required | Values | Description |
690+
|-----------|----------|--------|-------------|
691+
| **location** | Yes | `local`, `int`, `stg`, `prod`, or custom | Environment where instance runs |
692+
| **role** | Yes | `author`, `publish` | AEM instance role |
693+
| **classifier** | No | `1`, `2`, `preview`, or custom | Distinguishes multiple instances with same location and role |
694+
695+
> **⚠️ Important:** The `local` location prefix is **required** for local instance management commands (`aem instance local create`, `start`, `stop`, `launch`, `delete`, `backup`, etc.).
696+
>
697+
> Instances with any other location (e.g., `int_`, `stg_`, `prod_`) are treated as **remote** and will be **skipped** by local management commands, even if their `http_url` points to localhost.
698+
699+
### Example Instance IDs
700+
701+
| ID | Description |
702+
|----|-------------|
703+
| `local_author` | Local author instance (developer machine) |
704+
| `local_publish` | Local publish instance (developer machine) |
705+
| `int_author` | Integration environment author |
706+
| `int_publish` | Integration environment publish |
707+
| `int_publish_preview` | Integration publish preview instance |
708+
| `stg_author` | Staging environment author |
709+
| `prod_publish_1` | Production publish instance #1 |
710+
| `prod_publish_2` | Production publish instance #2 |
711+
| `prod_author_us` | Production author for US region |
712+
713+
### Using Instance IDs
714+
715+
Instance IDs can be used in multiple places:
716+
717+
**1. CLI flags:**
718+
```shell
719+
# Target specific instance by ID
720+
sh aemw package deploy --file my-package.zip --instance-id local_author
721+
722+
# Target by URL (ad-hoc)
723+
sh aemw package deploy --file my-package.zip --instance-url http://localhost:4502
724+
725+
# Filter by role
726+
sh aemw instance status --instance-author # Only author instances
727+
sh aemw instance status --instance-publish # Only publish instances
728+
```
729+
730+
**2. Configuration in `aem.yml`:**
731+
```yaml
732+
instance:
733+
config:
734+
local_author:
735+
http_url: http://127.0.0.1:4502
736+
user: admin
737+
password: admin
738+
run_modes: [ local ]
739+
local_publish:
740+
http_url: http://127.0.0.1:4503
741+
user: admin
742+
password: admin
743+
int_author:
744+
http_url: https://author.int.example.com
745+
user: admin
746+
password: ${AEM_INT_PASSWORD}
747+
int_publish:
748+
http_url: https://publish.int.example.com
749+
user: admin
750+
password: ${AEM_INT_PASSWORD}
751+
```
752+
753+
**3. Environment variables** (override config):
754+
```shell
755+
# Activate/deactivate specific instances
756+
export AEM_INSTANCE_CONFIG_LOCAL_AUTHOR_ACTIVE=true
757+
export AEM_INSTANCE_CONFIG_LOCAL_PUBLISH_ACTIVE=false
758+
export AEM_INSTANCE_CONFIG_INT_AUTHOR_ACTIVE=true
759+
```
760+
675761
# Examples
676762

763+
## Managing Local Instances
764+
765+
```shell
766+
# Create and start local AEM instances
767+
sh aemw instance local create
768+
sh aemw instance local start
769+
770+
# Or do both in one command
771+
sh aemw instance local launch
772+
773+
# Check instance status
774+
sh aemw instance status
775+
776+
# Stop instances
777+
sh aemw instance local stop
778+
779+
# Delete instances (removes all data)
780+
sh aemw instance local delete
781+
```
782+
783+
## Deploying Packages
784+
785+
```shell
786+
# Deploy a single package
787+
sh aemw package deploy --file my-package.zip
788+
789+
# Deploy to specific instance
790+
sh aemw package deploy --file my-package.zip --instance-id local_author
791+
792+
# Deploy multiple packages
793+
sh aemw package deploy --file pkg1.zip --file pkg2.zip
794+
795+
# Deploy from URL
796+
sh aemw package deploy --url https://example.com/my-package.zip
797+
```
798+
799+
## OSGi Configuration
800+
801+
```shell
802+
# List all bundles
803+
sh aemw osgi bundle list
804+
805+
# Check specific bundle status
806+
sh aemw osgi bundle read --symbolic-name com.example.core
807+
808+
# Set OSGi configuration
809+
sh aemw osgi config save --pid com.example.MyService --input-string "enabled: true"
810+
```
811+
812+
## Repository Operations
813+
814+
```shell
815+
# Read node properties
816+
sh aemw repo node read --path /content/my-site
817+
818+
# Copy content between instances
819+
sh aemw content copy --path /content/my-site --instance-target-id local_publish
820+
```
821+
822+
## Instance Backups
823+
824+
Backups allow you to save and restore the complete state of local AEM instances.
825+
826+
**Format:** Backups use [Zstandard (zstd)](https://github.com/facebook/zstd) compression developed by Facebook - optimized for excellent compression ratio with very fast decompression speed. Files are stored in `aem/home/var/backup` directory with `.aemb.tar.zst` extension.
827+
828+
**Automatic instance handling:** All backup commands automatically stop running instances before operation and restart them afterwards. No manual stop/start is required.
829+
830+
### Basic Commands
831+
832+
```shell
833+
# List all available backups
834+
sh aemw instance local backup list
835+
836+
# Create backup of a single instance
837+
sh aemw instance local backup make --instance-id local_author
838+
839+
# Create backup with custom file path
840+
sh aemw instance local backup make --instance-id local_author --file my-backup.aemb.tar.zst
841+
842+
# Restore instance from backup (instance must not exist)
843+
sh aemw instance local backup use --instance-id local_author
844+
845+
# Restore from specific backup file
846+
sh aemw instance local backup use --instance-id local_author --file my-backup.aemb.tar.zst
847+
848+
# Restore and delete existing instance first
849+
sh aemw instance local backup use --instance-id local_author --delete-created
850+
```
851+
852+
### Backup & Restore Cycle
853+
854+
Backups enable safe experimentation - break your instance, restore in 10-15 minutes:
855+
856+
```shell
857+
# 1. Save current state before experimenting
858+
sh aemw instance local backup perform
859+
860+
# 2. Experiment freely (install packages, change configs, break things...)
861+
# ...
862+
863+
# 3. Something went wrong? Delete and restore from backup
864+
sh aemw instance local delete --kill
865+
sh aemw instance local backup restore
866+
```
867+
868+
Use cases:
869+
- Safe experimentation with risky configurations or packages
870+
- Quick recovery from broken instances without full reinstall
871+
- Testing different AEM versions or configurations
872+
- Sharing pre-configured instances via cloud storage (S3, GCS, Azure Blob)
873+
874+
**Backup file naming:** `{role}[-{classifier}]-{aem_version}-{timestamp}.aemb.tar.zst`
875+
**Example:** `author-6.5.21-20260209-143022.aemb.tar.zst`
876+
677877
## Replication agents
678878

679879
1. Configuring publish agent on AEM author:
680880

681881
```shell
682-
PROPS="
882+
sh aemw repl agent setup -A --location "author" --name "publish" --input-string "
683883
enabled: true
684884
transportUri: http://localhost:4503/bin/receive?sling:authRequestLogin=1
685885
transportUser: admin
686886
transportPassword: admin
687887
userId: admin
688888
"
689-
echo "$PROPS" | sh aemw repl agent setup -A --location "author" --name "publish"
690889
```
691890

692891
2. Configuring flush agent on AEM publish:
693892

694893
```shell
695-
PROPS="
894+
sh aemw repl agent setup -P --location "publish" --name "flush" --input-string "
696895
enabled: true
697896
transportUri: http://localhost/dispatcher/invalidate.cache
698897
protocolHTTPHeaders:
@@ -701,7 +900,6 @@ When configuring instances, AEMC automatically determines the type based on the
701900
- 'CQ-Path: {path}'
702901
- 'Host: flush'
703902
"
704-
echo "$PROPS" | sh aemw repl agent setup -P --location "publish" --name "flush"
705903
```
706904
If needed, update `localhost` to the value on which AEM dispatcher is available, e.g.`localhost:8080`.
707905

0 commit comments

Comments
 (0)