Modern Docker Management, Designed for Everyone
Go composecontainer-managementcontainersdockerdocker-composedocker-managementgoself-hostedsveltekittypescriptweb-ui
chore: change wording of readme
Kyle Mendellb42c01393df8
diff --git a/README.md b/README.mdindex 1d0d3041d..97d80924c 100644--- a/README.md+++ b/README.md@@ -1,34 +1,39 @@# Arcane - Docker Management UI-Arcane is a web-based user interface built with SvelteKit to interact with and manage your Docker environment. It provides a clean overview of your containers, images, volumes, and networks, along with controls for common Docker operations.+[](https://shields.io/)++**⚠️ Note:** Arcane is currently pre-release software. Features may change, and bugs are expected. Use with caution, especially in production environments.++Arcane is a web-based user interface built with SvelteKit designed to simplify interaction with your Docker environment. It provides a clean overview and management capabilities for your containers, images, volumes, and networks.## Features-- **Dashboard:** Overview of your Docker environment (coming soon).-- **Containers:** List, inspect, start, stop, restart, and remove containers. View container logs.-- **Images:** List and remove images.-- **Volumes:** List and manage Docker volumes.-- **Networks:** List and manage Docker networks.-- **Settings:** Configure Docker connection details (Host/Socket Path) and application preferences.-- **Responsive UI:** Built with shadcn-svelte and Tailwind CSS for a modern look and feel.+- **Containers:** List, inspect, start, stop, restart, and remove containers. View container logs. Create containers (basic implementation).+- **Images:** List, pull, and remove images. Prune unused images.+- **Volumes:** List, create, and remove volumes.+- **Networks:** List and remove networks.+- **Stacks:** Manage Docker Compose stacks (via `docker-compose` CLI integration - requires `docker-compose` accessible in the container/host).+- **Settings:** Configure Docker connection details (Host/Socket Path) and application preferences like polling interval.+- **Responsive UI:** Built with shadcn-svelte and Tailwind CSS for a modern look and feel on various devices.## Technology Stack-- **Frontend:** SvelteKit, TypeScript-- **UI Components:** shadcn-svelte+- **Framework:** SvelteKit+- **Language:** TypeScript+- **UI Components:** shadcn-svelte, Bits UI- **Styling:** Tailwind CSS- **Docker Interaction:** Dockerode (Node.js client for the Docker Engine API)- **Deployment:** Docker Compose## Prerequisites-- **Docker:** The Docker Engine must be installed and running.-- **Docker Compose:** Required for running the application via the provided configuration.-- **Node.js & npm/pnpm/yarn:** Required only for local development.+- **Docker Engine:** Must be installed and running.+- **Docker Compose:** Required for the recommended setup method. (Note: Also used internally for Stack management).+- **Node.js & npm/pnpm/yarn:** Required _only_ for local development.## Getting Started (Docker Compose - Recommended)-This is the easiest way to run Arcane, as it bundles the application and its dependencies.+This is the easiest and recommended way to run Arcane.1. **Clone the repository:**@@ -37,8 +42,13 @@ This is the easiest way to run Arcane, as it bundles the application and its depcd arcane```-2. **Docker Socket Access:**- The provided `docker-compose.yml` file mounts the Docker socket (`/var/run/docker.sock`) into the Arcane container. This allows Arcane to communicate with your local Docker Engine. Ensure the path to the Docker socket is correct for your system if it differs.+2. **Review Docker Compose Configuration (`docker-compose.yml`):**++ - **Docker Socket:** The service mounts `/var/run/docker.sock` by default. Ensure this path is correct for your system.+ - **Permissions:** The container needs permission to access the Docker socket. The `DOCKER_GID` environment variable is set to `998` in the example. You may need to adjust this to match the group ID of the `docker` group on your host system. Find it using: `getent group docker | cut -d: -f3`+ - **Data Persistence:** The `./arcane-data:/app/data` volume mapping persists stack definitions and potentially other application data outside the container in the `arcane-data` directory.+ - **User/Group IDs:** `PUID` and `PGID` are set for file ownership within the persistent volume. Adjust as needed for your host user.+ - **Port:** The application runs on port `3000` by default.3. **Build and Run:**@@ -46,12 +56,14 @@ This is the easiest way to run Arcane, as it bundles the application and its depdocker-compose up -d```+ This will pull the `ghcr.io/ofkm/arcane:latest` image and start the container in the background.+4. **Access Arcane:**- Open your web browser and navigate to `http://localhost:3000` (or the port specified in your `docker-compose.yml` if you changed it).+ Open your web browser and navigate to `http://localhost:3000` (or the port you configured).## Development (Local)-If you want to contribute or run the application locally for development:+If you want to contribute or run the application directly using Node.js:1. **Clone the repository:**@@ -68,24 +80,54 @@ If you want to contribute or run the application locally for development:```3. **Configure Docker Connection:**- By default, Arcane will try to connect to the Docker socket at `/var/run/docker.sock`. If your Docker setup is different, you can modify the default in `src/lib/services/docker-service.ts` or configure it via the Settings page once the application is running (settings are saved to `app-settings.json` in the project root).++ - Arcane attempts to connect to the Docker socket specified in `app-settings.json` (defaults to `/var/run/docker.sock` if the file doesn't exist or the setting is missing).+ - Ensure your local Node.js process has permissions to access the Docker socket.+ - You can modify connection settings via the UI (**Settings** page) once running, which updates `app-settings.json`.4. **Start the development server:**```bash- npm run dev -- --open+ npm run dev+ # or npm run dev -- --open to open automatically```- This will start the SvelteKit development server, typically on `http://localhost:5173`.+ The application will typically be available at `http://localhost:5173`.## Configuration-Application settings, including the Docker host connection string, can be configured via the **Settings** page within the Arcane UI. These settings are persisted in the `app-settings.json` file in the project's root directory. When running via Docker Compose, this file will exist _inside_ the container unless you map a volume to persist it externally.+- Application settings are managed via the **Settings** page in the UI.+- These settings are stored in `app-settings.json` in the application's root data directory (`/app/data` inside the container, mapped to `./arcane-data` in the default compose setup).+- Key settings include:+ - `dockerHost`: Docker socket path or TCP address (e.g., `unix:///var/run/docker.sock` or `tcp://192.168.1.100:2375`).+ - `pollingInterval`: Auto-refresh interval in seconds (0 to disable).+ - `stacksDirectory`: Path where Docker Compose stack files are stored (relative to `/app/data`).++## Building for Production (Standalone Node.js)++While Docker Compose is recommended, you can build a production version:++1. **Build the application:**++ ```bash+ npm run build+ ```++ This creates a production-ready Node.js application in the `build` directory (using `adapter-node`).-## Building for Production (Standalone)+2. **Run the application:**-While Docker Compose is recommended, you can build a production version of the SvelteKit app:+ ```bash+ node build/index.js+ ```++ Ensure the Node.js environment has access to the Docker socket and the `app-settings.json` file (if needed). You might need to set environment variables or manage `app-settings.json` manually in this setup.++3. **Preview the build locally:**+ ```bash+ npm run preview+ ```-```bash-npm run build-```+## Important Notes-This requires a Node.js environment to run. You'll need an adapter (like `adapter-node`) configured in `svelte.config.js` for standalone deployment. See the [SvelteKit documentation on adapters](https://kit.svelte.dev/docs/adapters) for more details. You can preview the build locally with `npm run preview`.+- **Security:** Mounting the Docker socket (`/var/run/docker.sock`) into any container grants it root-level access to your Docker host. Understand the security implications before running Arcane or any container with socket access.+- **Pre-release:** This software is under active development. Expect breaking changes and bugs.+- **Data:** Stack definitions and application settings are stored in the mapped data volume (`./arcane-data` by default when using Docker Compose). Back up this directory if needed.