Skip to content
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

Update scaffolding and version nums when 0.4 is finally recommended #503

Merged
merged 9 commits into from
Dec 20, 2024
Merged

Update scaffolding and version nums when 0.4 is finally recommended #503

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
321d8cf
update for scaffolding 0.4000
pdaoust Dec 6, 2024
25ab4c9
update for scaffolding 0.4000.0-rc.4
pdaoust Dec 13, 2024
45dcfa6
bump version numbers in advanced install guide, plus new output from …
pdaoust Dec 20, 2024
feb4a04
Merge branch 'main' into 2024-12-06-updates-0.4
pdaoust Dec 20, 2024
f158c42
Merge branch 'main' into 2024-12-06-updates-0.4
pdaoust Dec 20, 2024
d2f4940
update ubuntu sandbox instructions to reflect that there's a new version
pdaoust Dec 20, 2024
e665745
Merge branch '2024-12-06-updates-0.4' of github.com:holochain/docs-pa…
pdaoust Dec 20, 2024
d5acdea
remove holo dev server from hn-introspect output
pdaoust Dec 20, 2024
504eabb
update holonix commands in getting started guide
pdaoust Dec 20, 2024
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
4 changes: 2 additions & 2 deletions src/pages/get-started/2-hello-world.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ cd ~/Holochain
When getting started, seeing a simple but fully-functional app can be very helpful. You can have Holochain's scaffolding tool generate a "Hello World!" application (but for a distributed multi-agent world) by typing the following in your command line terminal:

```shell
nix run github:holochain/holochain#hc-scaffold -- example hello-world
nix run github:holochain/holonix?ref=main-0.4#hc-scaffold -- example hello-world
```

The scaffolding tool will ask you one question --- what JavaScript package manager you'd like to use in your project. If in doubt, just choose `npm`.
Expand All @@ -43,7 +43,7 @@ Ubuntu Linux 24.04 [introduces security policy changes](https://discourse.ubuntu
sudo chown root:root node_modules/electron/dist/chrome-sandbox && sudo chmod 4755 node_modules/electron/dist/chrome-sandbox
```

You'll need to do this once (but only once) for every new project you scaffold. You can find out more [here](/get-started/install-advanced/#fixing-the-suid-sandbox-error-in-ubuntu-24-04).
You'll need to do this once (but only once) for every new project you scaffold. You can find out more [here](/get-started/install-advanced/#fixing-the-suid-sandbox-error-in-ubuntu-24-04-and-later).
!!!

```shell
Expand Down
87 changes: 51 additions & 36 deletions src/pages/get-started/3-forum-app-tutorial.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ First, let's use the scaffolding tool to generate the basic folders and files fo
To start, run the following command in your terminal:

```shell
nix run github:/holochain/holochain#hc-scaffold -- web-app
nix run github:/holochain/holonix?ref=0.4#hc-scaffold -- web-app
```

!!! info Backing out of a mistake
Expand Down Expand Up @@ -396,6 +396,24 @@ You should then see:
```text
Which fields should the entry contain?

? Field name: ›
```
:::

The scaffolding tool is now prompting you to add fields to the `post` entry type.

Fields are the individual components or attributes within a Rust struct. They determine the specific pieces of information to be stored in an entry and their respective data types. The scaffolding tool supports a collection of native Rust types such as booleans, numbers, enums (a choice between several predetermined values), optional values, and vectors (lists of items of the same type), along with Holochain-specific types that refer to other pieces of data on the DHT.

For your `post` entry type, you're going to add `title` and `content` fields. Enter the name of the first field:

```text
title
```

Next, it asks you to choose a field type:

::: output-block
```text
? Choose field type: ›
❯ String
bool
Expand All @@ -406,24 +424,15 @@ Which fields should the entry contain?
ActionHash
EntryHash
DnaHash
ExternalHash
AgentPubKey
Enum
Option of...
Vector of...
```
:::

The scaffolding tool is now prompting you to add fields to the `post` entry type.

Fields are the individual components or attributes within a Rust struct. They determine the specific pieces of information to be stored in an entry and their respective data types. The scaffolding tool supports a collection of native Rust types such as booleans, numbers, enums (a choice between several predetermined values), optional values, and vectors (lists of items of the same type), along with Holochain-specific types that refer to other pieces of data on the DHT.

For your `post` entry type, you're going to add `title` and `content` fields. Select `String` as the first field's type, and enter:

```text
title
```

as the field name.
Choose `String` and press <kbd>Enter</kbd>.

Press <kbd>Y</kbd> for the field to be visible in the UI, and select `TextField` as the widget to render this field. (A `TextField` is a single-line input field designed for capturing shorter pieces of text.)

Expand All @@ -437,17 +446,24 @@ When you see:

press <kbd>Y</kbd>.

Select `String` for this field's type too. Then enter:
Then enter the name `content` for this field's name and choose `String` as its type. Press <kbd>Y</kbd> for the field to be visible in the UI, and select `TextArea` as the widget to render the field. (A `TextArea` is a multi-line input field that allows users to enter larger blocks of text. That'll work better for forum posts.)

```text
content
```
After adding the `title` and `content` fields, press <kbd>N</kbd> when asked if you want to add another field. Next, you should see:

as the field name.
::: output-block
```text
Chosen fields:
title: String
content: String

Press <kbd>Y</kbd> for the field to be visible in the UI, and select `TextArea` as the widget to render the field. (A `TextArea` is a multi-line input field that allows users to enter larger blocks of text. That'll work better for blog posts.)
? Do you want to proceed with the current entry type or restart from the beginning? ›
❯ Confirm
pdaoust marked this conversation as resolved.
Show resolved Hide resolved
Modify
Restart
```
:::

After adding the `title` and `content` fields, press <kbd>N</kbd> when asked if you want to add another field. Next, you should see:
If the summary of your fields looks like this, press <kbd>Enter</kbd> to confirm that it's correct. Next, you'll see:

::: output-block
```text
Expand Down Expand Up @@ -537,19 +553,13 @@ comment

for the entry type name.

You're going to add a `content` field, so select the `String` field type and enter:

```text
content
```

Then select the `TextArea` widget and press <kbd>Enter</kbd>. (Again, a `TextArea` is a multi-line input field that allows users to enter larger blocks of text. Perfect for a comment on a post.)
Next, create a `content` field and select `String` as its type. Choose <kbd>Y</kbd> to create UI for it, then select the `TextArea` widget and press <kbd>Enter</kbd>. (Again, a `TextArea` is a multi-line input field that allows users to enter larger blocks of text. Perfect for a comment on a post.)

Press <kbd>Y</kbd> to add another field.

For this next field you'll want to create a field that will help you associate each particular comment to the post that it's commenting on. To do this, the next field in the `comment` entry type will store a reference to a `post`.

Use the arrow keys to select `ActionHash` as the field type.
Enter `post_hash` as the field name, press <kbd>Enter</kbd>, and use the arrow keys to select `ActionHash` as the field type.

!!! dig-deeper Hashes and other identifiers

Expand Down Expand Up @@ -599,7 +609,7 @@ You can check out the Core Concepts to dive a bit deeper into [how the distribut

!!!

After press <kbd>Enter</kbd>, you should see:
After pressing <kbd>Enter</kbd>, you should see:

::: output-block
```text
Expand All @@ -614,20 +624,25 @@ Next you will see:
::: output-block
```text
✔ Which entry type is this field referring to?
❯ Post
```
:::

Press <kbd>Enter</kbd> to accept the suggested entry type `Post`.
Press <kbd>Enter</kbd> to accept the suggested entry type `Post`. Then press <kbd>N</kbd> to decline adding another field to the entry.

Next, you'll be asked to pick a field name. You can press <kbd>Enter</kbd> to accept the field name suggestion, which should be:
You should then see a similar confirmation to when you were creating a post:

::: output-block
```text
post_hash
Chosen fields:
content: String, post_hash: ActionHash
? Do you want to proceed with the current entry type or restart from the beginning? ›
❯ Confirm
Restart
```
:::

Press <kbd>N</kbd> to decline adding another field to the entry.

Then use the arrow keys to deselect `Update`, but leave `Delete` selected. It should look as follows:
If the summary looks like this, press <kbd>Enter</kbd>. Then at the next question, use the arrow keys to deselect `Update`, but leave `Delete` selected. It should look as follows:

::: output-block
```text
Expand All @@ -637,7 +652,7 @@ Which CRUD functions should be scaffolded (SPACE to select/unselect, ENTER to co
```
:::

Once that is done, press <kbd>Enter</kbd> to generate a delete function for the **`comment`** entry type.
Once that is done, press <kbd>Enter</kbd> to generate a delete function for the `comment` entry type.

You should then see:

Expand Down Expand Up @@ -778,7 +793,7 @@ Ubuntu Linux 24.04 [introduces security policy changes](https://discourse.ubuntu
sudo chown root:root node_modules/electron/dist/chrome-sandbox && sudo chmod 4755 node_modules/electron/dist/chrome-sandbox
```

You'll need to do this once (but only once) for every new project you scaffold. You can find out more [here](/get-started/install-advanced/#fixing-the-suid-sandbox-error-in-ubuntu-24-04).
You'll need to do this once (but only once) for every new project you scaffold. You can find out more [here](/get-started/install-advanced/#fixing-the-suid-sandbox-error-in-ubuntu-24-04-and-later).
!!!

At this stage, we'll incorporate some of the UI components that have been scaffolded by the scaffolding tool into our main application interface. Our aim here is to make all the functionality of our forum application accessible from a single, unified interface. We'll use Svelte to accomplish this, as it is the framework that we have chosen for the UI layer of our application.
Expand Down
6 changes: 3 additions & 3 deletions src/pages/get-started/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ This command downloads the setup script and runs it, installing the Nix package
In a new terminal session type:

```shell
nix run --refresh -j0 -v github:holochain/holochain#hc-scaffold -- --version
nix run --refresh -j0 -v github:holochain/holonix?ref=main-0.4#hc-scaffold -- --version
```

Look out for binaries being copied from `holochain-ci.cachix.org`:
Expand All @@ -80,11 +80,11 @@ downloading 'https://holochain-ci.cachix.org/nar/<some-hash>.nar.zst'...

It proves that the package cache is configured correctly.

At the end of the output, Holochain's scaffolding tool should print its version string:
At the end of the output, Holochain's scaffolding tool should print its version string, which will be something like this:

::: output-block
```text
holochain_scaffolding_cli x.y.z
holochain_scaffolding_cli 0.4000.?
```
:::

Expand Down
37 changes: 26 additions & 11 deletions src/pages/get-started/install-advanced.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,26 +24,26 @@ If you want to learn more about how this setup works and how to create it manual
The flake-based one-liner to get you an ad-hoc Holonix shell (that is, not using a local flake file) looks like this:

```shell
nix develop github:holochain/holonix?ref=main-0.3
nix develop github:holochain/holonix?ref=main-0.4
```

#### Specifying a certain release

The above one-liner will give you the latest **recommended** version of Holochain from the 0.3 release branch. To get an ad-hoc shell with a different version of Holochain, change the `ref` parameter. For example, if you want to enter a Holochain 0.4 development shell, run:
The above one-liner will give you the latest **recommended** version of Holochain from the 0.4 release branch. To get an ad-hoc shell with a specific version of Holochain, change the `ref` parameter. For example, if you want to enter a Holochain 0.3 development shell, run:

```shell
nix develop github:holochain/holonix?ref=main-0.4
nix develop github:holochain/holonix?ref=main-0.3
```

The options you should know about are:

* `main` or no `ref` parameter: The development version of Holochain, released weekly with no guarantee of stability (currently 0.5)
* `main-0.4`: The latest version of Holochain, which has not yet had a 'recommended' release
* `main-0.3`: The recommended version of Holochain for everyday development, which still receives maintenance releases
* `main-0.4`: The current recommended version of Holochain for everyday development
* `main-0.3`: The previous version of Holochain, which still receives maintenance releases

### Customizing the Holochain binary

If you want to enable or disable certain Holochain features, such as unstable features, it's best to do this in a local flake file. [Read the 'Customized Holochain build'](https://github.com/holochain/holonix?tab=readme-ov-file#customized-holochain-build) on the Holonix readme to find out how. Keep in mind that, because you'll be creating a custom Holochain binary, you won't be able to take advantage of the package cache, so it'll take a while to compile Holochain on your machine. The same will be true on CI, where you should consider setting up your own caching.
If you want to enable or disable certain Holochain features, such as unstable features, it's best to do this in a local flake file. Read [Customized Holochain build](https://github.com/holochain/holonix?tab=readme-ov-file#customized-holochain-build) on the Holonix readme to find out how. Keep in mind that, because you'll be creating a custom Holochain binary, you won't be able to take advantage of the package cache, so it'll take a while to compile Holochain on your machine. The same will be true on CI, where you should consider setting up your own caching.

### A gotcha with Flakes and Git

Expand All @@ -65,10 +65,25 @@ This command displays versioning information about Holochain's main components.

::: output-block
```text
holochain (holochain 0.1.3): ed5b7bb461c2a8bfd4d2633bad604a20b8f2da03
lair-keystore (lair_keystore 0.2.3): cbfbefefe43073904a914c8181a450209a74167b
hc-launch (holochain_cli_launch 0.0.11): 3bcd14e81cda07e015071b070c2ef032aa1d1193
hc-scaffold (holochain_scaffolding_cli 0.1.6): 0d84d09a9a3f41d3b7d7330a0797a789c42fd57f
hc-scaffold : holochain_scaffolding_cli 0.4000.0 (cda8433)
hc-launch : holochain_cli_launch 0.400.0 (holochain 0.4.0) (ca59803)
Lair keystore : lair_keystore 0.5.3 (e829375)
Holochain : holochain 0.4.0 (f931190)

Holochain build info: {
"git_info": null,
"cargo_pkg_version": "0.4.0",
"hdk_version_req": "0.4.0",
"hdi_version_req": "0.5.0",
"lair_keystore_version_req": "0.5.3",
"timestamp": "2024-12-18T19:25:03.915833743Z",
"hostname": "localhost",
"host": "x86_64-unknown-linux-gnu",
"target": "x86_64-unknown-linux-gnu",
"rustc_version": "rustc 1.80.0 (051478957 2024-07-21)",
"rustflags": "",
"profile": "release"
}
```
:::

Expand Down Expand Up @@ -102,7 +117,7 @@ The main Nix tool used in Holochain development workflows is `nix develop`, a pr

The full suite of Nix tooling is broad and deep. There's even a dedicated programming language, called [Nix expressions](https://nixos.org/manual/nix/stable/#functional-package-language). Learn more with the [NixOS Wiki](https://nixos.wiki) or the [Pills](https://nixos.org/nixos/nix-pills/) Tutorial. The [NixOS community chat on matrix.to](https://matrix.to/#/#community:nixos.org) is active and helpful.

## Fixing the SUID sandbox error in Ubuntu 24.04
## Fixing the SUID sandbox error in Ubuntu 24.04 and later

Ubuntu 24.04 [introduced an AppArmor security policy](https://discourse.ubuntu.com/t/ubuntu-24-04-lts-noble-numbat-release-notes/39890#unprivileged-user-namespace-restrictions-15) that causes `hc spin`, which is used to test applications and their UIs, to fail with a fatal error. If you have a `package.json` that lists `@holochain/hc-spin` as a dev dependency, you may see this error message:

Expand Down
4 changes: 2 additions & 2 deletions src/pages/resources/upgrade/upgrade-holochain-0.3.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,7 @@ npm install --save-dev @holochain/hc-spin@">=0.300.0 <0.400.0"
You can always check what versions of `@holochain/hc-spin` are available on the [NPM registry](https://www.npmjs.com/package/@holochain/hc-spin?activeTab=versions).

!!! note
If you happen to be running on a recent Linux version (e.g. Ubuntu 24.04+), you might encounter an error starting your hApp with `hc-spin`. There is a guide here you should check out in [the dev tools setup tips](/get-started/install-advanced#fixing-the-suid-sandbox-error-in-ubuntu-24-04).
If you happen to be running on a recent Linux version (e.g. Ubuntu 24.04+), you might encounter an error starting your hApp with `hc-spin`. There is a guide here you should check out in [the dev tools setup tips](/get-started/install-advanced#fixing-the-suid-sandbox-error-in-ubuntu-24-04-and-later).
!!!

### Update `@holochain/tryorama`
Expand Down Expand Up @@ -292,7 +292,7 @@ If you depend on other Holochain crates, then you will need to find compatible v
It's likely that you will need to make more changes than have been mentioned above, but hopefully this guide has given you a head start! Here are some other things to look out for in this upgrade:

* There have been significant changes to Holochain's data validation. You may see validation failures that you didn't see before upgrading. Our experience of helping people upgrade to dev versions of 0.3 is that these are often due to issues in your app's validation logic, and simply weren't caught before due to issues in Holochain's validation workflow. Please check your validation logic and check whether there might be an issue there. If not, then please reach out on Discord or open a [Github issue](https://github.com/holochain/holochain/issues/new/choose) for help.
* There have been changes to the data structures provided for app validation. This means that you will need to update your validation code to remove some fields that are no longer available. You should check the changelog [here](https://github.com/holochain/holochain/blob/develop-0.3/CHANGELOG.md#hdi-040-beta-dev36). If you need to retain the fields that have been removed for your validation logic, then your best option is probably to scaffold an app for 0.3 and take a look at how its validation code retrieves data that's no longer part of the data structures. You can do this by running `nix run --override-input versions "github:holochain/holochain?dir=versions/0_3" github:holochain/holochain#hc-scaffold`.
* There have been changes to the data structures provided for app validation. This means that you will need to update your validation code to remove some fields that are no longer available. You should check the changelog [here](https://github.com/holochain/holochain/blob/develop-0.3/CHANGELOG.md#hdi-040-beta-dev36). If you need to retain the fields that have been removed for your validation logic, then your best option is probably to scaffold an app for 0.3 and take a look at how its validation code retrieves data that's no longer part of the data structures. You can do this by running `nix run github:holochain/holonix?ref=main-0.3#hc-scaffold -- web-app`.
* There have been significant WebSocket app interface changes for Holochain 0.3. There is a changelog entry [here](https://github.com/holochain/holochain/blob/develop-0.3/CHANGELOG.md#holochain-030-beta-dev47). Most problems will be taken care of by picking the right client versions and following any changes that are required to use the new client. However, if you are integrating with Holochain's app interface directly or maintaining your own client then you should get in touch if you run into any difficulties upgrading.
* Databases prior to 0.3 have been unencrypted by default. From 0.3 onwards, databases are always encrypted by default. You can disable this by building Holochain with different options if you need to, or we can show you how to open the encrypted databases. For now, we are assuming that people don't often need to do this, so there is no guide. If this assumption turns out to be wrong, we can create one!
* A change was made to help hApp developers spot mistakes in DNA manifests that might catch you out if they contain extra fields or obsolete fields. You can read about this change [here](https://github.com/holochain/holochain/blob/develop-0.3/CHANGELOG.md#holochain_types-030-beta-dev24).
Expand Down
Loading