Modern Docker Management, Designed for Everyone
Go composecontainer-managementcontainersdockerdocker-composedocker-managementgoself-hostedsveltekittypescriptweb-ui
docs: update install guide and building docs
Kyle Mendell0249b5839a8b
diff --git a/contributing.md b/contributing.mdnew file mode 100644index 000000000..1bb2d2ccb--- /dev/null+++ b/contributing.md@@ -0,0 +1,68 @@+---+sidebar_position: 2+title: Contributing+---++# Contributing to Arcane++Thank you for your interest in contributing to Arcane! We welcome contributions from the community to help make Arcane better. Whether it's reporting a bug, suggesting a feature, or writing code, your help is appreciated.++## Ways to Contribute++- **Reporting Bugs:** If you encounter a bug, please help us by submitting a detailed bug report. Use the [**Bug Report**](https://github.com/ofkm/arcane/issues/new?template=bug.yml) template on GitHub.+- **Suggesting Features:** Have an idea for a new feature or an enhancement? We'd love to hear it! Use the [**Feature Request**](https://github.com/ofkm/arcane/issues/new?template=feature.yml) template on GitHub.+- **Code Contributions:** If you'd like to contribute code, please follow the process outlined below.+- **Documentation:** Improvements to the documentation are always welcome.++## Code Contribution Process++1. **Fork the Repository:** Start by forking the main Arcane repository on GitHub.+2. **Clone Your Fork:** Clone your forked repository to your local machine:+ ```bash+ git clone https://github.com/<your-username>/arcane.git+ cd arcane+ ```+3. **Create a Branch:** Create a new branch for your feature or bug fix. Use a descriptive name:+ ```bash+ git branch -m feature/my-new-feature+ # or+ git branch -m fix/issue-123+ ```+4. **Set Up Development Environment:** Follow the instructions in the [**Building from Source**](./building.md) guide to install dependencies and ensure you can run the development server.+ ```bash+ npm install+ npm run dev+ ```+5. **Make Changes:** Implement your feature or bug fix. Write clear, concise code.+6. **Lint and Format:** Ensure your code adheres to the project's style guidelines by running the linters and formatters:+ ```bash+ npm run lint+ npm run format+ ```+ Fix any issues reported.+7. **Commit Changes:** Commit your changes with a clear and descriptive commit message. Consider using [Conventional Commits](https://www.conventionalcommits.org/) if applicable.+ ```bash+ git add .+ git commit -m "feat: Add feature X"+ # or+ git commit -m "fix: Resolve issue Y"+ ```+8. **Keep Your Branch Updated:** Periodically update your branch with the latest changes from the upstream repository:+ ```bash+ git fetch upstream+ git rebase upstream/main+ ```+9. **Push Your Branch:** Push your changes to your forked repository:+ ```bash+ git push origin feature/my-new-feature+ ```+10. **Open a Pull Request:** Go to the original Arcane repository on GitHub and open a Pull Request (PR) from your branch to the main branch of the upstream repository.+ - Provide a clear title and description for your PR.+ - Reference any related issues (e.g., "Closes #123").+ - Be prepared to discuss your changes and make adjustments based on feedback.++## Code Style++Arcane uses [ESLint](https://eslint.org/) and [Prettier](https://prettier.io/) to enforce code style and consistency. Please run `npm run lint` and `npm run format` before committing your changes. Configuration files (`.eslint.config.js`, `.prettierrc`) are included in the repository.++Thank you again for contributing to Arcane!diff --git a/docker-compose.yml b/docker-compose.ymlindex 14ce54efa..5099fa4a1 100644--- a/docker-compose.yml+++ b/docker-compose.yml@@ -7,12 +7,12 @@ services:volumes:- /var/run/docker.sock:/var/run/docker.sock- ./arcane-data:/app/data-environment:- PUID=1000- PGID=1000- DOCKER_GID=998 # getent group docker | cut -d: -f3restart: unless-stopped+# Optional: Define the volume if you want Docker to manage it# volumes:# arcane-data:diff --git a/docs/docs/development/building.md b/docs/docs/development/building.mdindex 76c903ea0..884cf6c35 100644--- a/docs/docs/development/building.md+++ b/docs/docs/development/building.md@@ -1,5 +1,5 @@----sidebar_position: 3+sidebar_position: 2title: Building from Source---@@ -9,10 +9,10 @@ This guide explains how to build the Arcane application from its source code. Th## Prerequisites-- **Node.js:** Version 18.x or higher is recommended (check `.nvmrc` if present).-- **npm, yarn, or pnpm:** A Node.js package manager. Examples will use `npm`.-- **Git:** Required to clone the repository.-- **Docker Engine:** Required if you intend to build the Docker image.+- Node.js: Version 22 or higher.+- npm, yarn, pnpm, or bun: A Node.js package manager. Examples will use `npm`.+- Git: Required to clone the repository.+- Docker Engine: Required if you intend to build the Docker image, and test functionality locally.## Steps@@ -44,7 +44,7 @@ This guide explains how to build the Arcane application from its source code. ThThis will start a local development server, typically accessible at `http://localhost:3000` .-4. **Linting and Formatting (Optional):**+4. **Linting and Formatting:**Before building, you might want to check for code style issues:```bash@@ -84,14 +84,7 @@ The repository includes a `Dockerfile` to containerize the application.You can replace `arcane-local` with your preferred image tag.3. **Run the Docker Container:**- Once built, you can run the image similarly to the official image, ensuring you mount the Docker socket and potentially a data volume:- ```bash- docker run -d -p 3000:3000 \- -v /var/run/docker.sock:/var/run/docker.sock \- -v ./arcane-data:/app/data \- --name arcane-dev \- arcane-local- ```+See the [Quickstart](/docs/getting-started/quickstart) guide on how to run the docker container.This covers the essential steps for building and running Arcane from its source code, both as a standalone Node.js application and as a Docker image.diff --git a/docs/docs/development/contributing.md b/docs/docs/development/contributing.mdindex b91939851..fd34f594f 100644--- a/docs/docs/development/contributing.md+++ b/docs/docs/development/contributing.md@@ -1,5 +1,5 @@----sidebar_position: 2+sidebar_position: 1title: Contributing---@@ -22,45 +22,41 @@ Thank you for your interest in contributing to Arcane! We welcome contributionsgit clone https://github.com/<your-username>/arcane.gitcd arcane```-3. **Set Upstream Remote:** Add the original repository as the upstream remote:+3. **Create a Branch:** Create a new branch for your feature or bug fix. Use a descriptive name:```bash- git remote add upstream https://github.com/ofkm/arcane.git- ```-4. **Create a Branch:** Create a new branch for your feature or bug fix. Use a descriptive name:- ```bash- git checkout -b feature/my-new-feature+ git branch -m feature/my-new-feature# or- git checkout -b fix/issue-123+ git branch -m fix/issue-123```-5. **Set Up Development Environment:** Follow the instructions in the [**Building from Source**](./building.md) guide to install dependencies and ensure you can run the development server.+4. **Set Up Development Environment:** Follow the instructions in the [**Building from Source**](./building.md) guide to install dependencies and ensure you can run the development server.```bashnpm installnpm run dev```-6. **Make Changes:** Implement your feature or bug fix. Write clear, concise code.-7. **Lint and Format:** Ensure your code adheres to the project's style guidelines by running the linters and formatters:+5. **Make Changes:** Implement your feature or bug fix. Write clear, concise code.+6. **Lint and Format:** Ensure your code adheres to the project's style guidelines by running the linters and formatters:```bashnpm run lintnpm run format```Fix any issues reported.-8. **Commit Changes:** Commit your changes with a clear and descriptive commit message. Consider using [Conventional Commits](https://www.conventionalcommits.org/) if applicable.+7. **Commit Changes:** Commit your changes with a clear and descriptive commit message. Consider using [Conventional Commits](https://www.conventionalcommits.org/) if applicable.```bashgit add .git commit -m "feat: Add feature X"# orgit commit -m "fix: Resolve issue Y"```-9. **Keep Your Branch Updated:** Periodically update your branch with the latest changes from the upstream repository:+8. **Keep Your Branch Updated:** Periodically update your branch with the latest changes from the upstream repository:```bashgit fetch upstreamgit rebase upstream/main```-10. **Push Your Branch:** Push your changes to your forked repository:+9. **Push Your Branch:** Push your changes to your forked repository:```bashgit push origin feature/my-new-feature```-11. **Open a Pull Request:** Go to the original Arcane repository on GitHub and open a Pull Request (PR) from your branch to the main branch of the upstream repository.+10. **Open a Pull Request:** Go to the original Arcane repository on GitHub and open a Pull Request (PR) from your branch to the main branch of the upstream repository.- Provide a clear title and description for your PR.- Reference any related issues (e.g., "Closes #123").- Be prepared to discuss your changes and make adjustments based on feedback.diff --git a/docs/docs/getting-started/configuration.md b/docs/docs/getting-started/configuration.mdindex c4a403ff3..11b4c3999 100644--- a/docs/docs/getting-started/configuration.md+++ b/docs/docs/getting-started/configuration.md@@ -93,7 +93,7 @@ services:# ... other settingsvolumes:- /var/run/docker.sock:/var/run/docker.sock # Mount Docker socket- - ./arcane-data:/app/data # Mount data directory+ - arcane-data:/app/data # Mount data directory# ... other settings```@@ -126,4 +126,4 @@ services:## Initial Setup-When you first access Arcane, you'll be guided through a setup process where you can configure these settings. You can modify them later at any time through the Settings page in the web UI.+When you first access Arcane, you'll be guided through a setup process where you can configure the essential settings. You can modify them later at any time through the Settings page in the web UI.diff --git a/docs/docs/getting-started/quickstart.md b/docs/docs/getting-started/quickstart.mdindex 30ba76e90..31568c944 100644--- a/docs/docs/getting-started/quickstart.md+++ b/docs/docs/getting-started/quickstart.md@@ -5,47 +5,64 @@ title: Quick Start# Quick Start Guide-This guide provides the fastest way to get Arcane up and running using Docker Compose, which is the recommended method.+This guide provides the fastest way to get Arcane up and running using Docker Compose, the recommended method.## Prerequisites-- **Docker and Docker Compose:** Installed and running.-- **Git:** Installed (optional only for cloning the repository).+- `Docker and Docker Compose`## Steps-1. **Clone the Repository:**- Open your terminal and clone the Arcane repository:+1. **Create `docker-compose.yml`:**+ Create a `docker-compose.yml` file with the following content:- ```bash- git clone https://github.com/ofkm/arcane- cd arcane- ```+```yaml+services:+ arcane:+ image: ghcr.io/ofkm/arcane:latest+ container_name: arcane+ ports:+ - '3000:3000'+ volumes:+ - /var/run/docker.sock:/var/run/docker.sock+ - arcane-data:/app/data+ environment:+ - PUID=1000+ - PGID=1000+ - DOCKER_GID=998 # getent group docker | cut -d: -f3+ restart: unless-stopped++volumes:+ arcane-data:+ driver: local+```++You may need to modify the environment variables to fit your setup. Mainly the `DOCKER_GID` variable.++2. **Review Configuration & Permissions:**+ Before starting, review the `docker-compose.yml` file:-2. **Review Docker Compose Configuration (Optional but Recommended):**- Take a quick look at the `docker-compose.yml` file provided in the repository. Key things to note:+ - **Docker Socket:** It mounts `/var/run/docker.sock` (read-only) to allow Arcane to manage Docker.- - **Docker Socket:** It mounts `/var/run/docker.sock` by default.- - **Data Persistence:** It maps `./arcane-data` on your host to `/app/data` in the container to store settings and stack definitions.- - **Permissions:** It uses `PUID`, `PGID`, and `DOCKER_GID` environment variables. You might need to adjust `DOCKER_GID` to match your host's Docker group ID. Find it using:- ```bash- getent group docker | cut -d: -f3- ```- Update the `DOCKER_GID` value in `docker-compose.yml` if necessary. The default `PUID` and `PGID` of `1000` are often suitable but can be changed if needed.+ - **Data Persistence:**: You can mount a volume or local mount to `/app/data` inside the container. This will store Arcane's settings, stacks, users, sessions, and encryption keys.++ - **Permissions (Important):**++ - The `PUID` and `PGID` (default `1000`) control the ownership of the `/app/data` volume inside the container. Adjust if your user ID/group ID is different.++ - You **must** set `DOCKER_GID` to match the group ID of the Docker socket (`/var/run/docker.sock`) on your host machine. This allows Arcane to communicate with Docker. Find your Docker group ID using one of these commands in your terminal:+ - Linux: `getent group docker | cut -d: -f3`+ - Linux (alternative): `stat -c '%g' /var/run/docker.sock`+ - macOS (if Docker group exists): `dscl . -read /Groups/docker PrimaryGroupID | awk '{print $2}'` (Often not needed on standard Docker Desktop for Mac setups).+ - Update the `DOCKER_GID=999` line in the `docker-compose.yml` file with the correct ID.3. **Start Arcane:**- Run the following command from the `arcane` directory:+ Open your terminal, navigate to the directory where you saved `docker-compose.yml`, and run:```bashdocker-compose up -d```- This command will:-- - Pull the latest `ghcr.io/ofkm/arcane:latest` image.- - Create and start the Arcane container in the background.- - Create the `./arcane-data` directory on your host if it doesn't exist.-4. **Access Arcane:**Open your web browser and navigate to:diff --git a/docs/src/pages/index.tsx b/docs/src/pages/index.tsxindex dd6f433c9..221949427 100644--- a/docs/src/pages/index.tsx+++ b/docs/src/pages/index.tsx@@ -25,7 +25,7 @@ function HomepageHeader() {<Link className={styles.buttonPrimary} to="/docs/">Get Started</Link>- <Link className={styles.buttonSecondary} href="https://github.com/your-username/arcane" target="_blank" rel="noopener noreferrer">+ <Link className={styles.buttonSecondary} href="https://github.com/ofkm/arcane" target="_blank" rel="noopener noreferrer">GitHub</Link></div>