diff --git a/assets/ui/ui-dev-webstorm-container-selection.png b/assets/ui/ui-dev-webstorm-container-selection.png new file mode 100644 index 000000000..5193fef76 Binary files /dev/null and b/assets/ui/ui-dev-webstorm-container-selection.png differ diff --git a/assets/ui/ui-dev-webstorm-new-container-creation.png b/assets/ui/ui-dev-webstorm-new-container-creation.png new file mode 100644 index 000000000..4f667f18f Binary files /dev/null and b/assets/ui/ui-dev-webstorm-new-container-creation.png differ diff --git a/assets/ui/ui-dev-webstorm-new-docker-connection-setup.png b/assets/ui/ui-dev-webstorm-new-docker-connection-setup.png new file mode 100644 index 000000000..7e1c245dc Binary files /dev/null and b/assets/ui/ui-dev-webstorm-new-docker-connection-setup.png differ diff --git a/assets/ui/ui-dev-webstorm-remote-project-initialization.png b/assets/ui/ui-dev-webstorm-remote-project-initialization.png new file mode 100644 index 000000000..6f89dc170 Binary files /dev/null and b/assets/ui/ui-dev-webstorm-remote-project-initialization.png differ diff --git a/dev.md b/dev.md index 6352e1c56..5a7f7cd65 100644 --- a/dev.md +++ b/dev.md @@ -2,7 +2,7 @@ title: Developers description: Getting started on Wiki.js development published: true -date: 2022-06-11T20:18:43.212Z +date: 2024-10-31T02:12:28.000Z tags: dev editor: markdown dateCreated: 2019-02-15T04:25:01.768Z @@ -10,7 +10,9 @@ dateCreated: 2019-02-15T04:25:01.768Z Wiki.js is fully modular, which allows any developer to write their own module. -There are 3 methods to develop for Wiki.js. You can either use the dockerized development environment for VS Code *(recommended)*, a generic docker environment or install all dependencies manually on your machine. +There are 4 methods to develop for Wiki.js. You can either use the dockerized development environment for VS Code *(recommended)*, the remote development environment for WebStorm, a generic docker environment or install all dependencies manually on your machine. + +> JetBrains WebStorm was recently, October 2024, made free with a community version for **non-commercial** use. For more details see ยง2, paragraph 3 of the [Toolbox Subscription Agreement for Non-Commercial Use](https://www.jetbrains.com/legal/docs/toolbox/license_non-commercial/){.is-info} # Using Docker + Visual Studio Code @@ -47,8 +49,71 @@ Click on **File > Close Remote Connection** to stop the containers and close the When you're done and no longer need the development environment, open the **Remote Explorer** tab and remove all containers starting with the name `wiki`. +Alternatively, see the [generic method](#removing-the-containers-2) below. + +# Using Docker + JetBrains WebStorm + +> This section is under development + +## Prerequisites + +* Docker + Docker Compose (via [Docker Desktop](https://www.docker.com/products/docker-desktop/)) +* Linux / macOS / Windows 10-11 Pro or Enterprise +* [JetBrains WebStorm](https://www.jetbrains.com/webstorm/) + +> WebStorm on Linux can either be setup from the downloadable tarball or installing via Flathub. If using the Flathub version of WebStorm it executes webstorm.sh instead of webstorm from the /bin directory of the application and will give you a notification on startup.{.is-info} + +> WebStorm (*version 2024.2.4*) by default only has a **4.19 GB (4000 MiB) heap size** and can crash during development tasks of Wiki.js. To expand the limit, go to **Help** > **Change Memory Settings** and enter in the new value in MiB. When done, click **Save and Restart** so the changes take effect.{.is-info} + +## Running the project +1. Clone the project from [GitHub](https://github.com/Requarks/wiki). +2. Open the project folder in **WebStorm** +3. If a dev container is currently setup, right-click on the *devcontainer.json* file from the file tree and select **Dev Containers** > **Create Dev Container and Mount Sources** > **ContainerName** > **WebStorm** and skip to [Starting Dev Container](#starting-dev-container). + +### Setting Up A New Dev Container +1. From the **File** menu, go to Remote Development and select the **Dev Containers** connections option +2. Click on **New Dev Container** to start creating a new container. + ![ui-dev-webstorm-container-selection.png](/assets/ui/ui-dev-webstorm-container-selection.png =400x){.radius-5 .decor-shadow .ml-5} +3. Change the dev container source to **From Local Project** from **From VCS Project** and either enter the path to the *devcontainer.json* file in the cloned repo or navigate to it by clicking on the folder icon. + ![ui-dev-webstorm-new-container-creation.png](/assets/ui/ui-dev-webstorm-new-container-creation.png =400px){.radius-5 .decor-shadow .ml-5} + +> The IDE can be changed to another product offered by JetBrains from WebStorm, but since development of Wiki.js is based in JavaScript there is no reason to change this.{.is-info} + +> If a red circle appears next to the name of the Docker container (*as shown in the above picture*) ensure that Docker Desktop is running on your machine.{.is-info} + +4. If a Docker Container already exists (*or was imported from VS Code to WebStorm*), skip this step and proceed to step 7 to start the development container. + 1. To create a new Docker Container in WebStorm, click on the **...** next to the first drop-down list on the new dev container creation window. + 2. Click on the **+** icon to create a new Docker container. + 3. Setup the Docker daemon connection settings using either a *Unix socket* or a *TCP socket*. A **Unix Socket** is the easiest connection to setup as it works directly with Docker Desktop. + 4. Change the name of the container, if desired, and click **OK** to complete the new container setup and initialize the Docker container startup. + ![ui-dev-webstorm-new-docker-connection-setup.png](/assets/ui/ui-dev-webstorm-new-docker-connection-setup =500px){.radius-5 .decor-shadow .ml-5} + +> If the connection for the selected Unix socket cannot locate the Docker daemon, choose from another available Docker Unix socket and see if the status changes to *Connection successful*.{.is-info} + +### Starting Dev Container +1. Once the container finishes initializing, a notification will pop up saying **Dev Container build is finished** and will prompt you to connect to the container. Click **Connect** from either the notification or from the Services pane to start the development connection. +2. Once the development IDE instance is created a new IDE window will pop up and the title bar will now show the remote connection type. The connection dropdown can be clicked on to view information about the Docker environment. To start Wiki.js in development mode, open the *Terminal* pane and enter the following command: + ```bash + yarn dev + ``` +3. Wait for the initialization to complete. Once the initialization process is completed, a message will appear above the terminal saying **Your application is listening on ports: 3000 forward to xxxx**. +4. Click on the forwarded port number to expand the dropdown list and click on **Open in browser**. + ![ui-dev-webstorm-remote-project-intialization.png](ui/assets/ui-dev-webstorm-remote-project-intialization.png =400px){.radius-5 .decor-shadow .ml-5} + +5. Complete the setup wizard to finish the installation. + +## Stopping the project + +To stop the remote connection, simply close the remote IDE window and stop the dev container service in the main WebStorm IDE window. + +## Removing the containers + +When you're done and no longer need the development environment, go back to **File** > **Remote Development** and remove any development containers created that are no longer needed. + Alternatively, see the [generic method](#removing-the-containers-1) below. + + # Using Docker (Generic) ## Prerequisites