Skip to content

Modern Docker Management, Designed for Everyone

docs: update install guide and building docs

Kyle Mendell0249b5839a8b
diff --git a/contributing.md b/contributing.md
new file mode 100644
index 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.yml
index 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: -f3
restart: 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.md
index 76c903ea0..884cf6c35 100644
--- a/docs/docs/development/building.md
+++ b/docs/docs/development/building.md
@@ -1,5 +1,5 @@
---
-sidebar_position: 3
+sidebar_position: 2
title: 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. Th
This 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.md
index b91939851..fd34f594f 100644
--- a/docs/docs/development/contributing.md
+++ b/docs/docs/development/contributing.md
@@ -1,5 +1,5 @@
---
-sidebar_position: 2
+sidebar_position: 1
title: Contributing
---
@@ -22,45 +22,41 @@ Thank you for your interest in contributing to Arcane! We welcome contributions
git clone https://github.com/<your-username>/arcane.git
cd 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.
```bash
npm install
npm 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:
```bash
npm run lint
npm 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.
```bash
git add .
git commit -m "feat: Add feature X"
# or
git 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:
```bash
git fetch upstream
git 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:
```bash
git 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.md
index c4a403ff3..11b4c3999 100644
--- a/docs/docs/getting-started/configuration.md
+++ b/docs/docs/getting-started/configuration.md
@@ -93,7 +93,7 @@ services:
# ... other settings
volumes:
- /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.md
index 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:
```bash
docker-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.tsx
index 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>