Skip to content

Modern Docker Management, Designed for Everyone

chore: change wording of readme

Kyle Mendellb42c01393df8
diff --git a/README.md b/README.md
index 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.
+[![Status](https://img.shields.io/badge/status-pre--release-orange)](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 dep
cd 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 dep
docker-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.