From 13773c4af0c4589fcd726765c3c02d9af30d02eb Mon Sep 17 00:00:00 2001 From: James Murdza Date: Thu, 28 Aug 2025 04:53:46 -0400 Subject: [PATCH 1/3] Split Lumier section into pages --- docs/content/docs/libraries/lumier/docker.mdx | 52 +++++++++++++++ docs/content/docs/libraries/lumier/index.mdx | 66 ++----------------- .../docs/libraries/lumier/installation.mdx | 7 ++ docs/content/docs/libraries/lumier/meta.json | 7 ++ 4 files changed, 71 insertions(+), 61 deletions(-) create mode 100644 docs/content/docs/libraries/lumier/docker.mdx create mode 100644 docs/content/docs/libraries/lumier/installation.mdx create mode 100644 docs/content/docs/libraries/lumier/meta.json diff --git a/docs/content/docs/libraries/lumier/docker.mdx b/docs/content/docs/libraries/lumier/docker.mdx new file mode 100644 index 00000000..3038f1c9 --- /dev/null +++ b/docs/content/docs/libraries/lumier/docker.mdx @@ -0,0 +1,52 @@ +--- +title: Docker +--- + +You can use Lumier through Docker: + +### Run a macOS VM (ephemeral) +```bash +docker run -it --rm \ + --name macos-vm \ + -p 8006:8006 \ + -e VM_NAME=macos-vm \ + -e VERSION=ghcr.io/trycua/macos-sequoia-cua:latest \ + -e CPU_CORES=4 \ + -e RAM_SIZE=8192 \ + trycua/lumier:latest +``` +Access the VM in your browser at [http://localhost:8006](http://localhost:8006). + +### Persistent Storage +```bash +mkdir -p storage + +docker run -it --rm \ + --name lumier-vm \ + -p 8006:8006 \ + -v $(pwd)/storage:/storage \ + -e VM_NAME=lumier-vm \ + -e VERSION=ghcr.io/trycua/macos-sequoia-cua:latest \ + -e CPU_CORES=4 \ + -e RAM_SIZE=8192 \ + -e HOST_STORAGE_PATH=$(pwd)/storage \ + trycua/lumier:latest +``` + +### Shared Folder +```bash +mkdir -p shared + +docker run -it --rm \ + --name lumier-vm \ + -p 8006:8006 \ + -v $(pwd)/storage:/storage \ + -v $(pwd)/shared:/shared \ + -e VM_NAME=lumier-vm \ + -e VERSION=ghcr.io/trycua/macos-sequoia-cua:latest \ + -e CPU_CORES=4 \ + -e RAM_SIZE=8192 \ + -e HOST_STORAGE_PATH=$(pwd)/storage \ + -e HOST_SHARED_PATH=$(pwd)/shared \ + trycua/lumier:latest +``` \ No newline at end of file diff --git a/docs/content/docs/libraries/lumier/index.mdx b/docs/content/docs/libraries/lumier/index.mdx index 3858504d..55e113e9 100644 --- a/docs/content/docs/libraries/lumier/index.mdx +++ b/docs/content/docs/libraries/lumier/index.mdx @@ -5,65 +5,9 @@ github: - https://github.com/trycua/cua/tree/main/libs/lumier --- -## Overview +**Lumier** is an interface for running macOS virtual machines with minimal setup. It uses Docker as a packaging system to deliver a pre-configured environment that connects to the `lume` virtualization service running on your host machine. With Lumier, you get: -The Lumier library provides a Docker-based interface for creating performant macOS virtual machines. - -## Installation - -**Requirements:** -- Docker for Apple Silicon (or compatible Mac) -- Lume virtualization CLI (install with: `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"`) - -## Usage - -### Run a macOS VM (ephemeral) -```bash -docker run -it --rm \ - --name macos-vm \ - -p 8006:8006 \ - -e VM_NAME=macos-vm \ - -e VERSION=ghcr.io/trycua/macos-sequoia-cua:latest \ - -e CPU_CORES=4 \ - -e RAM_SIZE=8192 \ - trycua/lumier:latest -``` -Access the VM in your browser at [http://localhost:8006](http://localhost:8006). - -### Persistent Storage -```bash -mkdir -p storage - -docker run -it --rm \ - --name lumier-vm \ - -p 8006:8006 \ - -v $(pwd)/storage:/storage \ - -e VM_NAME=lumier-vm \ - -e VERSION=ghcr.io/trycua/macos-sequoia-cua:latest \ - -e CPU_CORES=4 \ - -e RAM_SIZE=8192 \ - -e HOST_STORAGE_PATH=$(pwd)/storage \ - trycua/lumier:latest -``` - -### Shared Folder -```bash -mkdir -p shared - -docker run -it --rm \ - --name lumier-vm \ - -p 8006:8006 \ - -v $(pwd)/storage:/storage \ - -v $(pwd)/shared:/shared \ - -e VM_NAME=lumier-vm \ - -e VERSION=ghcr.io/trycua/macos-sequoia-cua:latest \ - -e CPU_CORES=4 \ - -e RAM_SIZE=8192 \ - -e HOST_STORAGE_PATH=$(pwd)/storage \ - -e HOST_SHARED_PATH=$(pwd)/shared \ - trycua/lumier:latest -``` - ---- - -See the [Lumier README](https://github.com/trycua/cua/tree/main/libs/lumier) for advanced options, Docker Compose setup, and automation scripts. \ No newline at end of file +- A ready-to-use macOS or Linux virtual machine in minutes +- Browser-based VNC access to your VM +- Easy file sharing between your host and VM +- Simple configuration through environment variables \ No newline at end of file diff --git a/docs/content/docs/libraries/lumier/installation.mdx b/docs/content/docs/libraries/lumier/installation.mdx new file mode 100644 index 00000000..63db702a --- /dev/null +++ b/docs/content/docs/libraries/lumier/installation.mdx @@ -0,0 +1,7 @@ +--- +title: Installation +--- + +**Requirements:** +- Docker for Apple Silicon (or compatible Mac) +- Lume virtualization CLI (install with: `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"`) \ No newline at end of file diff --git a/docs/content/docs/libraries/lumier/meta.json b/docs/content/docs/libraries/lumier/meta.json new file mode 100644 index 00000000..a24ac050 --- /dev/null +++ b/docs/content/docs/libraries/lumier/meta.json @@ -0,0 +1,7 @@ +{ + "pages": [ + "installation", + "docker", + "docker-compose" + ] +} From b724a136666c444c0754e1b5801c6745b9a740bf Mon Sep 17 00:00:00 2001 From: James Murdza Date: Thu, 28 Aug 2025 06:07:52 -0400 Subject: [PATCH 2/3] Move text from README to Cua documentation --- .../docs/libraries/lumier/building-lumier.mdx | 42 ++++ .../docs/libraries/lumier/docker-compose.mdx | 45 ++++ docs/content/docs/libraries/lumier/docker.mdx | 134 +++++++++--- docs/content/docs/libraries/lumier/index.mdx | 13 +- .../docs/libraries/lumier/installation.mdx | 13 +- docs/content/docs/libraries/lumier/meta.json | 3 +- libs/lumier/README.md | 202 +----------------- 7 files changed, 219 insertions(+), 233 deletions(-) create mode 100644 docs/content/docs/libraries/lumier/building-lumier.mdx create mode 100644 docs/content/docs/libraries/lumier/docker-compose.mdx diff --git a/docs/content/docs/libraries/lumier/building-lumier.mdx b/docs/content/docs/libraries/lumier/building-lumier.mdx new file mode 100644 index 00000000..df8ad4f8 --- /dev/null +++ b/docs/content/docs/libraries/lumier/building-lumier.mdx @@ -0,0 +1,42 @@ +--- +title: Building Lumier +--- + +If you want to customize the Lumier container or build it from source, you can follow these steps: + +```bash +# 1. Navigate to the Lumier directory +cd libs/lumier + +# 2. Build the Docker image locally +docker build -t lumier-custom:latest . + +# 3. Run your custom build +docker run -it --rm \ + --name lumier-vm \ + -p 8006:8006 \ + -e VM_NAME=lumier-vm \ + -e VERSION=ghcr.io/trycua/macos-sequoia-cua:latest \ + -e CPU_CORES=4 \ + -e RAM_SIZE=8192 \ + lumier-custom:latest +``` + +### Customization Options + +The Dockerfile provides several customization points: + +1. **Base image**: The container uses Debian Bullseye Slim as the base. You can modify this if needed. +2. **Installed packages**: You can add or remove packages in the apt-get install list. +3. **Hooks**: Check the `/run/hooks/` directory for scripts that run at specific points during VM lifecycle. +4. **Configuration**: Review `/run/config/constants.sh` for default settings. + +After making your modifications, you can build and push your custom image to your own Docker Hub repository: + +```bash +# Build with a custom tag +docker build -t yourusername/lumier:custom . + +# Push to Docker Hub (after docker login) +docker push yourusername/lumier:custom +``` \ No newline at end of file diff --git a/docs/content/docs/libraries/lumier/docker-compose.mdx b/docs/content/docs/libraries/lumier/docker-compose.mdx new file mode 100644 index 00000000..fece3473 --- /dev/null +++ b/docs/content/docs/libraries/lumier/docker-compose.mdx @@ -0,0 +1,45 @@ +--- +title: Docker Compose +--- + +You can also use Docker Compose to run Lumier with a simple configuration file. Create a `docker-compose.yml` file with the following content: + +```yaml +version: '3' + +services: + lumier: + image: trycua/lumier:latest + container_name: lumier-vm + restart: unless-stopped + ports: + - "8006:8006" # Port for VNC access + volumes: + - ./storage:/storage # VM persistent storage + - ./shared:/shared # Shared folder accessible in the VM + environment: + - VM_NAME=lumier-vm + - VERSION=ghcr.io/trycua/macos-sequoia-cua:latest + - CPU_CORES=4 + - RAM_SIZE=8192 + - HOST_STORAGE_PATH=${PWD}/storage + - HOST_SHARED_PATH=${PWD}/shared + stop_signal: SIGINT + stop_grace_period: 2m +``` + +Then run Lumier using: + +```bash +# First create the required directories +mkdir -p storage shared + +# Start the container +docker-compose up -d + +# View the logs +docker-compose logs -f + +# Stop the container when done +docker-compose down +``` diff --git a/docs/content/docs/libraries/lumier/docker.mdx b/docs/content/docs/libraries/lumier/docker.mdx index 3038f1c9..35ea859b 100644 --- a/docs/content/docs/libraries/lumier/docker.mdx +++ b/docs/content/docs/libraries/lumier/docker.mdx @@ -6,47 +6,117 @@ You can use Lumier through Docker: ### Run a macOS VM (ephemeral) ```bash +# Run the container with temporary storage (using pre-built image from Docker Hub) docker run -it --rm \ - --name macos-vm \ - -p 8006:8006 \ - -e VM_NAME=macos-vm \ - -e VERSION=ghcr.io/trycua/macos-sequoia-cua:latest \ - -e CPU_CORES=4 \ - -e RAM_SIZE=8192 \ - trycua/lumier:latest + --name macos-vm \ + -p 8006:8006 \ + -e VM_NAME=macos-vm \ + -e VERSION=ghcr.io/trycua/macos-sequoia-cua:latest \ + -e CPU_CORES=4 \ + -e RAM_SIZE=8192 \ + trycua/lumier:latest ``` Access the VM in your browser at [http://localhost:8006](http://localhost:8006). -### Persistent Storage +After running the command above, you can access your macOS VM through a web browser (e.g., http://localhost:8006). + +> **Note:** With the basic setup above, your VM will be reset when you stop the container (ephemeral mode). This means any changes you make inside the macOS VM will be lost. See the section below for how to save your VM state. + +## Saving Your VM State + +To save your VM state between sessions (so your changes persist when you stop and restart the container), you'll need to set up a storage location: + ```bash +# First, create a storage directory if it doesn't exist mkdir -p storage +# Then run the container with persistent storage docker run -it --rm \ - --name lumier-vm \ - -p 8006:8006 \ - -v $(pwd)/storage:/storage \ - -e VM_NAME=lumier-vm \ - -e VERSION=ghcr.io/trycua/macos-sequoia-cua:latest \ - -e CPU_CORES=4 \ - -e RAM_SIZE=8192 \ - -e HOST_STORAGE_PATH=$(pwd)/storage \ - trycua/lumier:latest + --name lumier-vm \ + -p 8006:8006 \ + -v $(pwd)/storage:/storage \ + -e VM_NAME=lumier-vm \ + -e VERSION=ghcr.io/trycua/macos-sequoia-cua:latest \ + -e CPU_CORES=4 \ + -e RAM_SIZE=8192 \ + -e HOST_STORAGE_PATH=$(pwd)/storage \ + trycua/lumier:latest ``` -### Shared Folder -```bash -mkdir -p shared +This command creates a connection between a folder on your Mac (`$(pwd)/storage`) and a folder inside the Docker container (`/storage`). The `-v` flag (volume mount) and the `HOST_STORAGE_PATH` variable work together to ensure your VM data is saved on your host Mac. +## Sharing Files with Your VM + +To share files between your Mac and the virtual machine, you can set up a shared folder: + +```bash +# Create both storage and shared folders +mkdir -p storage shared + +# Run with both persistent storage and a shared folder docker run -it --rm \ - --name lumier-vm \ - -p 8006:8006 \ - -v $(pwd)/storage:/storage \ - -v $(pwd)/shared:/shared \ - -e VM_NAME=lumier-vm \ - -e VERSION=ghcr.io/trycua/macos-sequoia-cua:latest \ - -e CPU_CORES=4 \ - -e RAM_SIZE=8192 \ - -e HOST_STORAGE_PATH=$(pwd)/storage \ - -e HOST_SHARED_PATH=$(pwd)/shared \ - trycua/lumier:latest -``` \ No newline at end of file + --name lumier-vm \ + -p 8006:8006 \ + -v $(pwd)/storage:/storage \ + -v $(pwd)/shared:/shared \ + -e VM_NAME=lumier-vm \ + -e VERSION=ghcr.io/trycua/macos-sequoia-cua:latest \ + -e CPU_CORES=4 \ + -e RAM_SIZE=8192 \ + -e HOST_STORAGE_PATH=$(pwd)/storage \ + -e HOST_SHARED_PATH=$(pwd)/shared \ + trycua/lumier:latest +``` + +With this setup, any files you place in the `shared` folder on your Mac will be accessible from within the macOS VM, and vice versa. + +## Automating VM Startup with on-logon.sh + +You can automatically run scripts when the VM starts up by placing an `on-logon.sh` script in the shared folder's lifecycle directory. This is useful for setting up your VM environment each time it starts. + +```bash +# Create the lifecycle directory in your shared folder +mkdir -p shared/lifecycle + +# Create a sample on-logon.sh script +cat > shared/lifecycle/on-logon.sh << 'EOF' +#!/usr/bin/env bash + +# Create a file on the desktop +echo "Hello from Lumier!" > /Users/lume/Desktop/hello_lume.txt + +# You can add more commands to execute at VM startup +# For example: +# - Configure environment variables +# - Start applications +# - Mount network drives +# - Set up development environments +EOF + +# Make the script executable +chmod +x shared/lifecycle/on-logon.sh +``` + +The script will be automatically executed when the VM starts up. It runs in the VM context and has access to: + +- The `/Users/lume` user directory (home directory in the VM) +- The shared folder at `/Volumes/My Shared Files` inside the VM +- Any resources available to the VM + +This feature enables automation of VM setup without modifying the base VM image. + +## Configuration Options + +When running Lumier, you'll need to configure a few things: + +- **Port forwarding** (`-p 8006:8006`): Makes the VM's VNC interface accessible in your browser. If port 8006 is already in use, you can use a different port like `-p 8007:8006`. + +- **Environment variables** (`-e`): Configure your VM settings: + - `VM_NAME`: A name for your virtual machine + - `VERSION`: The macOS image to use + - `CPU_CORES`: Number of CPU cores to allocate + - `RAM_SIZE`: Memory in MB to allocate + - `HOST_STORAGE_PATH`: Path to save VM state (when using persistent storage) + - `HOST_SHARED_PATH`: Path to the shared folder (optional) + +- **Background service**: The `lume serve` service should be running on your host (starts automatically when you install Lume using the `install.sh` script above). \ No newline at end of file diff --git a/docs/content/docs/libraries/lumier/index.mdx b/docs/content/docs/libraries/lumier/index.mdx index 55e113e9..5cb33762 100644 --- a/docs/content/docs/libraries/lumier/index.mdx +++ b/docs/content/docs/libraries/lumier/index.mdx @@ -10,4 +10,15 @@ github: - A ready-to-use macOS or Linux virtual machine in minutes - Browser-based VNC access to your VM - Easy file sharing between your host and VM -- Simple configuration through environment variables \ No newline at end of file +- Simple configuration through environment variables + +## How It Works + +> **Note:** We're using Docker primarily as a convenient delivery mechanism, not as an isolation layer. Unlike traditional Docker containers, Lumier leverages the Apple Virtualization Framework (Apple Vz) through the `lume` CLI to create true virtual machines. + +Here's what's happening behind the scenes: + +1. The Docker container provides a consistent environment to run the Lumier interface +2. Lumier connects to the Lume service running on your host Mac +3. Lume uses Apple's Virtualization Framework to create a true macOS virtual machine +4. The VM runs with hardware acceleration using your Mac's native virtualization capabilities \ No newline at end of file diff --git a/docs/content/docs/libraries/lumier/installation.mdx b/docs/content/docs/libraries/lumier/installation.mdx index 63db702a..e0c20267 100644 --- a/docs/content/docs/libraries/lumier/installation.mdx +++ b/docs/content/docs/libraries/lumier/installation.mdx @@ -2,6 +2,13 @@ title: Installation --- -**Requirements:** -- Docker for Apple Silicon (or compatible Mac) -- Lume virtualization CLI (install with: `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)"`) \ No newline at end of file +Before using Lumier, make sure you have: + +1. **Docker for Apple Silicon** - download it [here](https://desktop.docker.com/mac/main/arm64/Docker.dmg) and follow the installation instructions. + +2. **Lume** - This is the virtualization CLI that powers Lumier. Install it with this command: +```bash +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)" +``` + +After installation, Lume runs as a background service and listens on port 7777. This service allows Lumier to create and manage virtual machines. If port 7777 is already in use on your system, you can specify a different port with the `--port` option when running the `install.sh` script. \ No newline at end of file diff --git a/docs/content/docs/libraries/lumier/meta.json b/docs/content/docs/libraries/lumier/meta.json index a24ac050..f6a8946c 100644 --- a/docs/content/docs/libraries/lumier/meta.json +++ b/docs/content/docs/libraries/lumier/meta.json @@ -2,6 +2,7 @@ "pages": [ "installation", "docker", - "docker-compose" + "docker-compose", + "building-lumier" ] } diff --git a/libs/lumier/README.md b/libs/lumier/README.md index 287a6e96..92cfc559 100644 --- a/libs/lumier/README.md +++ b/libs/lumier/README.md @@ -39,19 +39,6 @@ Before using Lumier, make sure you have: /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/lume/scripts/install.sh)" ``` -After installation, Lume runs as a background service and listens on port 7777. This service allows Lumier to create and manage virtual machines. If port 7777 is already in use on your system, you can specify a different port with the `--port` option when running the `install.sh` script. - -## How It Works - -> **Note:** We're using Docker primarily as a convenient delivery mechanism, not as an isolation layer. Unlike traditional Docker containers, Lumier leverages the Apple Virtualization Framework (Apple Vz) through the `lume` CLI to create true virtual machines. - -Here's what's happening behind the scenes: - -1. The Docker container provides a consistent environment to run the Lumier interface -2. Lumier connects to the Lume service running on your host Mac -3. Lume uses Apple's Virtualization Framework to create a true macOS virtual machine -4. The VM runs with hardware acceleration using your Mac's native virtualization capabilities - ## Getting Started ```bash @@ -68,191 +55,14 @@ docker run -it --rm \ After running the command above, you can access your macOS VM through a web browser (e.g., http://localhost:8006). -> **Note:** With the basic setup above, your VM will be reset when you stop the container (ephemeral mode). This means any changes you make inside the macOS VM will be lost. See the section below for how to save your VM state. +> **Note:** With the basic setup above, your VM will be reset when you stop the container (ephemeral mode). This means any changes you make inside the macOS VM will be lost. See [the documentation](https://trycua.com/docs/libraries/lumier/docker) for how to save your VM state. -## Saving Your VM State +## Docs -To save your VM state between sessions (so your changes persist when you stop and restart the container), you'll need to set up a storage location: - -```bash -# First, create a storage directory if it doesn't exist -mkdir -p storage - -# Then run the container with persistent storage -docker run -it --rm \ - --name lumier-vm \ - -p 8006:8006 \ - -v $(pwd)/storage:/storage \ - -e VM_NAME=lumier-vm \ - -e VERSION=ghcr.io/trycua/macos-sequoia-cua:latest \ - -e CPU_CORES=4 \ - -e RAM_SIZE=8192 \ - -e HOST_STORAGE_PATH=$(pwd)/storage \ - trycua/lumier:latest -``` - -This command creates a connection between a folder on your Mac (`$(pwd)/storage`) and a folder inside the Docker container (`/storage`). The `-v` flag (volume mount) and the `HOST_STORAGE_PATH` variable work together to ensure your VM data is saved on your host Mac. - -## Sharing Files with Your VM - -To share files between your Mac and the virtual machine, you can set up a shared folder: - -```bash -# Create both storage and shared folders -mkdir -p storage shared - -# Run with both persistent storage and a shared folder -docker run -it --rm \ - --name lumier-vm \ - -p 8006:8006 \ - -v $(pwd)/storage:/storage \ - -v $(pwd)/shared:/shared \ - -e VM_NAME=lumier-vm \ - -e VERSION=ghcr.io/trycua/macos-sequoia-cua:latest \ - -e CPU_CORES=4 \ - -e RAM_SIZE=8192 \ - -e HOST_STORAGE_PATH=$(pwd)/storage \ - -e HOST_SHARED_PATH=$(pwd)/shared \ - trycua/lumier:latest -``` - -With this setup, any files you place in the `shared` folder on your Mac will be accessible from within the macOS VM, and vice versa. - -## Automating VM Startup with on-logon.sh - -You can automatically run scripts when the VM starts up by placing an `on-logon.sh` script in the shared folder's lifecycle directory. This is useful for setting up your VM environment each time it starts. - -```bash -# Create the lifecycle directory in your shared folder -mkdir -p shared/lifecycle - -# Create a sample on-logon.sh script -cat > shared/lifecycle/on-logon.sh << 'EOF' -#!/usr/bin/env bash - -# Create a file on the desktop -echo "Hello from Lumier!" > /Users/lume/Desktop/hello_lume.txt - -# You can add more commands to execute at VM startup -# For example: -# - Configure environment variables -# - Start applications -# - Mount network drives -# - Set up development environments -EOF - -# Make the script executable -chmod +x shared/lifecycle/on-logon.sh -``` - -The script will be automatically executed when the VM starts up. It runs in the VM context and has access to: - -- The `/Users/lume` user directory (home directory in the VM) -- The shared folder at `/Volumes/My Shared Files` inside the VM -- Any resources available to the VM - -This feature enables automation of VM setup without modifying the base VM image. - -## Using Docker Compose - -You can also use Docker Compose to run Lumier with a simple configuration file. Create a `docker-compose.yml` file with the following content: - -```yaml -version: '3' - -services: - lumier: - image: trycua/lumier:latest - container_name: lumier-vm - restart: unless-stopped - ports: - - "8006:8006" # Port for VNC access - volumes: - - ./storage:/storage # VM persistent storage - - ./shared:/shared # Shared folder accessible in the VM - environment: - - VM_NAME=lumier-vm - - VERSION=ghcr.io/trycua/macos-sequoia-cua:latest - - CPU_CORES=4 - - RAM_SIZE=8192 - - HOST_STORAGE_PATH=${PWD}/storage - - HOST_SHARED_PATH=${PWD}/shared - stop_signal: SIGINT - stop_grace_period: 2m -``` - -Then run Lumier using: - -```bash -# First create the required directories -mkdir -p storage shared - -# Start the container -docker-compose up -d - -# View the logs -docker-compose logs -f - -# Stop the container when done -docker-compose down -``` - -## Building and Customizing Lumier - -If you want to customize the Lumier container or build it from source, you can follow these steps: - -```bash -# 1. Navigate to the Lumier directory -cd libs/lumier - -# 2. Build the Docker image locally -docker build -t lumier-custom:latest . - -# 3. Run your custom build -docker run -it --rm \ - --name lumier-vm \ - -p 8006:8006 \ - -e VM_NAME=lumier-vm \ - -e VERSION=ghcr.io/trycua/macos-sequoia-cua:latest \ - -e CPU_CORES=4 \ - -e RAM_SIZE=8192 \ - lumier-custom:latest -``` - -### Customization Options - -The Dockerfile provides several customization points: - -1. **Base image**: The container uses Debian Bullseye Slim as the base. You can modify this if needed. -2. **Installed packages**: You can add or remove packages in the apt-get install list. -3. **Hooks**: Check the `/run/hooks/` directory for scripts that run at specific points during VM lifecycle. -4. **Configuration**: Review `/run/config/constants.sh` for default settings. - -After making your modifications, you can build and push your custom image to your own Docker Hub repository: - -```bash -# Build with a custom tag -docker build -t yourusername/lumier:custom . - -# Push to Docker Hub (after docker login) -docker push yourusername/lumier:custom -``` - -## Configuration Options - -When running Lumier, you'll need to configure a few things: - -- **Port forwarding** (`-p 8006:8006`): Makes the VM's VNC interface accessible in your browser. If port 8006 is already in use, you can use a different port like `-p 8007:8006`. - -- **Environment variables** (`-e`): Configure your VM settings: - - `VM_NAME`: A name for your virtual machine - - `VERSION`: The macOS image to use - - `CPU_CORES`: Number of CPU cores to allocate - - `RAM_SIZE`: Memory in MB to allocate - - `HOST_STORAGE_PATH`: Path to save VM state (when using persistent storage) - - `HOST_SHARED_PATH`: Path to the shared folder (optional) - -- **Background service**: The `lume serve` service should be running on your host (starts automatically when you install Lume using the `install.sh` script above). +- [Installation](https://trycua.com/docs/libraries/lumier/installation) +- [Docker](https://trycua.com/docs/libraries/lumier/docker) +- [Docker Compose](https://trycua.com/docs/libraries/lumier/docker-compose) +- [Building Lumier](https://trycua.com/docs/libraries/lumier/building-lumier) ## Credits From 1626094590ecfaa842039cca2bb1164b5fddab89 Mon Sep 17 00:00:00 2001 From: James Murdza Date: Thu, 28 Aug 2025 06:22:24 -0400 Subject: [PATCH 3/3] Use callouts for notes --- docs/content/docs/libraries/lumier/docker.mdx | 4 +++- docs/content/docs/libraries/lumier/index.mdx | 4 +++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/content/docs/libraries/lumier/docker.mdx b/docs/content/docs/libraries/lumier/docker.mdx index 35ea859b..4ecd15d6 100644 --- a/docs/content/docs/libraries/lumier/docker.mdx +++ b/docs/content/docs/libraries/lumier/docker.mdx @@ -20,7 +20,9 @@ Access the VM in your browser at [http://localhost:8006](http://localhost:8006). After running the command above, you can access your macOS VM through a web browser (e.g., http://localhost:8006). -> **Note:** With the basic setup above, your VM will be reset when you stop the container (ephemeral mode). This means any changes you make inside the macOS VM will be lost. See the section below for how to save your VM state. + +With the basic setup above, your VM will be reset when you stop the container (ephemeral mode). This means any changes you make inside the macOS VM will be lost. See the section below for how to save your VM state. + ## Saving Your VM State diff --git a/docs/content/docs/libraries/lumier/index.mdx b/docs/content/docs/libraries/lumier/index.mdx index 5cb33762..814055ba 100644 --- a/docs/content/docs/libraries/lumier/index.mdx +++ b/docs/content/docs/libraries/lumier/index.mdx @@ -14,7 +14,9 @@ github: ## How It Works -> **Note:** We're using Docker primarily as a convenient delivery mechanism, not as an isolation layer. Unlike traditional Docker containers, Lumier leverages the Apple Virtualization Framework (Apple Vz) through the `lume` CLI to create true virtual machines. + +We're using Docker primarily as a convenient delivery mechanism, not as an isolation layer. Unlike traditional Docker containers, Lumier leverages the Apple Virtualization Framework (Apple Vz) through the `lume` CLI to create true virtual machines. + Here's what's happening behind the scenes: