From 6b39aa577a03992220258070b37bd97e49e55b83 Mon Sep 17 00:00:00 2001 From: Brian Bollen Date: Fri, 13 Sep 2024 16:03:23 -0600 Subject: [PATCH] Updated loon docs --- .../docs/getting-started/index.md | 6 ++- .../docs/getting-started/loon-wrappers.md | 44 ++++++++++++++++--- 2 files changed, 43 insertions(+), 7 deletions(-) diff --git a/apps/docs-website/docs/getting-started/index.md b/apps/docs-website/docs/getting-started/index.md index 236c8d5..1983e3a 100644 --- a/apps/docs-website/docs/getting-started/index.md +++ b/apps/docs-website/docs/getting-started/index.md @@ -4,7 +4,7 @@ Below we list some core concepts of Loon and how to get started visualizing your ## Loon Variations -There are two distinct versions of Loon which will be supported. The standard Loon and **Local Loon**. Local Loon comes with all the features that the standard Loon supports except for data upload. Local Loon instead runs a simple server from a specified volume path where your data is already expected to reside. This is especially useful for users that do not need the data processing features and subsequent long wait times to process large amounts of data. +There are two distinct versions of Loon which will be supported. The standard Loon and **Local Loon**. Local Loon comes with all the features that the standard Loon supports except for data upload. Local Loon instead runs a simple server from a specified volume path where your data is already expected to reside in the correct format. This is especially useful for users that do not need the data processing features and subsequent long wait times to process large amounts of data. ## Installing and Running Loon @@ -17,3 +17,7 @@ If you're looking for the quickest way to get started with Loon, we suggest usin ### Building From Source If you require more custom configuration for your Loon application, consider building the Docker images from source. Unlike the official images, there is no need for a single wrapper image around the multi-container application. Instead, we leverage Docker Compose to create each container. While more technically challenging, building from source allows for more custom configuration and has a robust set of logs for debugging. See [here](./building-loon) for more information. + +import DocCardList from '@theme/DocCardList'; + + diff --git a/apps/docs-website/docs/getting-started/loon-wrappers.md b/apps/docs-website/docs/getting-started/loon-wrappers.md index 33a6218..edd3a0c 100644 --- a/apps/docs-website/docs/getting-started/loon-wrappers.md +++ b/apps/docs-website/docs/getting-started/loon-wrappers.md @@ -6,43 +6,75 @@ sidebar_position: 1 We support two official docker images for Loon -- a standard Loon version and a Local Loon version. Each of these images have Docker installed inside them and subsequently build the entire application for you. You can find the most up-to-date images below. -## Local Loon Image +## Working with Loon Images + +Working with the Loon Images requires very little set up. To start you should have [Docker](https://www.docker.com/) installed. Docker is a simple way to get complicated, multi-service applications up and running with little configuration. You can run any of the Loon images on your local computer using only the Docker Desktop UI. + +To start, you'll need to pull one of the two officially supported images. In Docker Desktop, you can search for the official images by typing in the name of the respective image. Then, pulling the image will create the image on your local Docker instance. You can view all your images in the left-hand sidebar of Docker Desktop. + +Once the image is pulled, you can run the image by clicking the "play" icon to the right of the image. This will create a container that will begin running the Loon image. + +:::warning +Note that each image requires two volume paths and an environment variable to be specified in order to run properly. In Docker desktop, you can adjust these values when clicking "run" on the image and then expanding the "Optional Settings" section. Please see below for the information that is required for your respective image. +::: + +## Debugging Your Loon Image + +Loon comes with a robust logging system that will help you debug in the case of any issues. By default, logs are outputted to the container and can be seen in the "Logs" tab when your container is running. Additionally, each of the separate services that run inside the Loon container will be separated in Docker for you to investigate. When you start the Loon container, another set of containers (named "build-files") will also be created. Expanding this in your Docker Desktop UI will show the statuses of each service that is running. You can independently check the logs for each of these containers. + +### Common Problems + +**Problem:** Docker says that "Redis" and "Data/MinIO" is running, but nothing else was able to run. What happened? + +**Solution:** Sometimes, when shutting down the container, the database that is used in Loon will not shutdown properly. Upon restart, the new database that is created will not have access to the proper port since it is still in use by the old database. This will prevent the rest of the applications from starting. To solve this, you can try restarting the Loon container. If that is not sufficient, deleting the containers and then re-run the base Loon image will solve the issue + +**Problem:** Docker states that my "Data/MinIO" container was not able to successfully start. + +**Solution:** When mounting the location of your local data to the container, Docker requires certain access to that directory in order to function. If the directory you are attempting to mount requires administrator privileges, you may not be able to mount that directory. Try using a directory that requires less privileges to access. + +## Loon Images + +### Local Loon To run this image, you will need to specify the location of your Docker socket to mount, the path where your data is currently located, and an additional environment variable. +Image Name in Docker Hub: bbollen23/local-loon + Image source: https://hub.docker.com/r/bbollen23/local-loon All Versions: https://hub.docker.com/r/bbollen23/local-loon/tags -### Volumes +#### Volumes | Volumes | Source | Destination | Details | | ----------------- | -------------------------- | -------------------- | ------------------------------------------------------- | | Docker Volume | /var/run/docker.sock | /var/run/docker.sock | This is required for to start nested docker containers. | | Local Data Volume | Absolute path to your data | /app/data | Location of where your data lives. | -### Environment Variables +#### Environment Variables | Environment Variable | Key | Value | Details | | -------------------- | -------------------------------------- | -------------------------- | ------------------------------------------------------- | | Local Data Volume | LOCALDATASETTINGS_SOURCEVOLUMELOCATION | Absolute path to your data | This will be identical to your Data Volume source path. | -## Standard Loon Image +### Standard Loon To run this image, you will need to specify the location of your Docker socket to mount, the path where you would like your data to be uploaded, and an additional environment variable. +Image Name in Docker Hub: bbollen23/loon + Image source: https://hub.docker.com/r/bbollen23/loon All Versions: https://hub.docker.com/r/bbollen23/loon/tags -### Volumes +#### Volumes | Volumes | Source | Destination | Details | | ----------------- | -------------------------- | -------------------- | ------------------------------------------------------- | | Docker Volume | /var/run/docker.sock | /var/run/docker.sock | This is required for to start nested docker containers. | | MinIO Data Volume | Absolute path to your data | /app/data | Location of where your data lives. | -### Environment Variables +#### Environment Variables | Environment Variable | Key | Value | Details | | -------------------- | ---------------------------------- | -------------------------- | ------------------------------------------------------- |