Skip to content

Expanded setup instructions #51

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Unisay merged 2 commits into from
Jul 23, 2025
+51 −17
Merged

Expanded setup instructions #51

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1c41cdd
Expanded setup instructions
rober-m Jul 18, 2025
9f9f26c
Apply suggestions from code review
rober-m Jul 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 51 additions & 17 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,38 +22,72 @@ Plinth currently supports GHC `v9.6.x`. Cabal `v3.8+` is recommended.

### 2. Setup your development environment

- With Nix (**recommended**)
<details>
<summary> With Nix (<b>recommended</b>) </summary>

Follow [these instructions](https://github.com/input-output-hk/iogx/blob/main/doc/nix-setup-guide.md) to install and configure nix, *even if you already have it installed*.
1. Follow [these instructions](https://github.com/input-output-hk/iogx/blob/main/doc/nix-setup-guide.md) to install and configure nix, <b>even if you already have it installed</b>.

2. Then enter the shell using `nix develop`.

Then enter the shell using `nix develop`.
> NOTE:
> The nix files inside this template follow the [`iogx` template](https://github.com/input-output-hk/iogx), but you can delete and replace them with your own. In that case, you might want to include the [`devx` flake](https://github.com/input-output-hk/devx/issues) in your flake inputs as a starting point to supply all the necessary dependencies, making sure to use one of the `-iog` flavors.

The nix files inside this template follow the [`iogx` template](https://github.com/input-output-hk/iogx), but you can delete and replace them with your own. In that case, you might want to include the [`devx` flake](https://github.com/input-output-hk/devx/issues) in your flake inputs as a starting point to supply all the necessary dependencies, making sure to use one of the `-iog` flavours.
> NOTE (for Windows users):<br>
> Make sure to have [WSL2](https://learn.microsoft.com/en-us/windows/wsl/install#upgrade-version-from-wsl-1-to-wsl-2) and the [WSL](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl) VSCode extension (if using VSCode) installed before the Nix setup.
</details>

- With Docker / Devcontainers / Codespaces
<details>
<summary> With Docker / Devcontainer / Codespaces </summary>

- **Docker + Codespaces:** From the [GitHub web page](https://github.com/IntersectMBO/plinth-template), click the top-right green button:

From the [GitHub web page](https://github.com/IntersectMBO/plinth-template), click the top-right green button:
`Use this template -> Open in a codespace`

`Use this template -> Open in a codespace`
- **Docker + Devcontainer:**
1. Make sure to have [VSCode](https://code.visualstudio.com/) installed with the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension.
2. Open this project in VSCode and let it create a local codespace for you (See Dev Containers instructions, if needed).

Or let VSCode create a local codespace for you when you open this project.
- **Stand-alone Docker:** Change the `/path/to/my-project` accordingly and run:

You can modify your [`devcontainer.json`](./.devcontainer/devcontainer.json) file to customize the container (more info [here](https://github.com/input-output-hk/devx?tab=readme-ov-file#vscode-devcontainer--github-codespace-support)).

Or using your local docker installation (change the `/path/to/my-project` accordingly):
```
docker run \
-v /path/to/my-project:/workspaces/my-project \
-it ghcr.io/input-output-hk/devx-devcontainer:x86_64-linux.ghc96-iog
docker run \
-v /path/to/my-project:/workspaces/my-project \
-it ghcr.io/input-output-hk/devx-devcontainer:x86_64-linux.ghc96-iog
```

When using this approach, you can ignore/delete/replace the nix files entirely.
> NOTE:
> You can modify your [`devcontainer.json`](./.devcontainer/devcontainer.json) file to customize the container (more info [here](https://github.com/input-output-hk/devx?tab=readme-ov-file#vscode-devcontainer--github-codespace-support)).

> NOTE:
> When using this approach, you can ignore/delete/replace the Nix files entirely.

> NOTE (for Windows users):<br>
> It is recommended to install and run Docker on your native OS. If you want to run Docker Desktop inside a VM, read through [these notes](https://docs.docker.com/desktop/setup/vm-vdi/).
</details>

<details>
<summary> With Demeter </summary>

1. Create an account in [Demeter](https://demeter.run/).

2. Follow [their instructions](https://docs.demeter.run/guides/getting-started) to setup a remote development environment.

> IMPORTANT:
> Demeter uses its own infrastructure and packages. If something is not working correctly, please contact them before creating an issue.

- With manually-installed dependencies (**not recommended**)
> NOTE:
> When using this approach, you can ignore/delete/replace the Nix files entirely.
</details>

<details>
<summary> With manually-installed dependencies (<b>not recommended</b>) </summary>
<br>

Follow the instructions for [cardano-node](https://developers.cardano.org/docs/get-started/cardano-node/installing-cardano-node/) for a custom setup.

When using this approach, you can ignore/delete/replace the nix files entirely.
> NOTE:
> When using this approach, you can ignore/delete/replace the Nix files entirely.
</details>

### 3. Run the example application

Expand Down