Setup & Deployment

Usage with Live-reload

For a quick start with a pre-configured environment, you can use the XeoContext Template (opens in a new tab).

1. Clone the template:

   git clone https://github.com/xeost/xeocontext-template my-system-design
   cd my-system-design

2. Run with Docker Compose: The template includes a docker-compose.yml configured to use the xeost/xeocontext-live-reload:latest image.

   docker compose up -d

3. Edit Content: Modify the files in the content directory. The viewer will automatically reload to reflect your changes. See Configuration and Structure & Organization for more details.

AI Support: The template includes .agent/rules/content.md, which provides instructions for LLMs on how to structure the design content (DDD, OpenAPI, AsyncAPI).

Note: The template provides a minimal starting point. For comprehensive examples of directory structures and configurations, please refer to the examples (opens in a new tab) directory in this repository.

Production Usage (without Live-reload)

If your content is static and will not be edited, you can switch to the production-optimized image for better performance.

1. Follow the steps in the Usage with Live-reload section to set up your repository.

2. Edit the docker-compose.yml file and change the image name:

   services:
     xeocontext:
       image: xeost/xeocontext:latest # Change from xeocontext-live-reload
       # ... rest of the configuration

Deployment on Vercel

This workflow allows you to deploy a customized version of XeoContext (with your embedded content) to Vercel.

1. Clone the XeoContext Viewer: Start by cloning the base viewer repository.

   git clone https://github.com/xeost/xeocontext.git my-viewer
   cd my-viewer
   pnpm install

2. Check Available Versions: See which versions of XeoContext are available to pin your deployment to.

   pnpm list-releases

3. Create Deployment Repository: Create a new empty repository on GitHub (e.g., github-user/system-design-example) where your customized viewer will live.

4. Configure Environment: Copy .env.example to .env and set the following variables:

   cp .env.example .env
   • XEOCONTEXT_CONTENT_TYPE: Set to 'local' (if content is on your machine) or 'git' (if content is in a remote repo).
   • XEOCONTEXT_CONTENT_SOURCE: Path to local directory (relative or absolute) or Git URL of your content repository.
   • XEOCONTEXT_TAG: The XeoContext version tag you want to use (e.g., v0.1.0).
   • XEOCONTEXT_DEPLOY_REPO: The URL of the GitHub repository you created in step 3.

5. Sync & Setup: Run the setup script. This will reset the code to the specified tag, copy your content into the content directory, and configure the git remotes (upstream for updates, origin for your deployment).

   pnpm setup-content

6. Push to GitHub: Commit the changes and push to your deployment repository.

   git add .
   git commit -m "Initial deployment"
   git push -u origin main

   Note: Connect this repository to Vercel for automatic deployments.

Maintaining Your Deployment

Updating XeoContext Version: If a new version of XeoContext is released:

1. Update XEOCONTEXT_TAG in your .env file.
2. Run pnpm setup-content.
3. Commit and push.

Updating Content: If you change your design content (in your local folder or external content repo):

1. Run pnpm setup-content.
2. Commit and push.

Development (Contributing)

1. Install dependencies:

   pnpm install

2. Configure Environment: Copy .env.example to .env and configure XEOCONTEXT_CONTENT_DIR to point to a sample content directory.

   cp .env.example .env

   Open .env and uncomment/set:

   XEOCONTEXT_CONTENT_DIR=./examples/markdown-openapi-asyncapi

3. Run development server:

   pnpm dev

4. Open Application: Navigate to http://localhost:12051 (opens in a new tab).