diff --git a/src/pages/get-started/2-hello-world.md b/src/pages/get-started/2-hello-world.md index 8de944202..aa9b435ca 100644 --- a/src/pages/get-started/2-hello-world.md +++ b/src/pages/get-started/2-hello-world.md @@ -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`. @@ -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 diff --git a/src/pages/get-started/3-forum-app-tutorial.md b/src/pages/get-started/3-forum-app-tutorial.md index 16c6721bd..07da7360d 100644 --- a/src/pages/get-started/3-forum-app-tutorial.md +++ b/src/pages/get-started/3-forum-app-tutorial.md @@ -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 @@ -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 @@ -406,6 +424,7 @@ Which fields should the entry contain? ActionHash EntryHash DnaHash + ExternalHash AgentPubKey Enum Option of... @@ -413,17 +432,7 @@ Which fields should the entry contain? ``` ::: -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 Enter. Press Y 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.) @@ -437,17 +446,24 @@ When you see: press Y. -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 Y 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 N 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 Y 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 + Modify + Restart +``` +::: -After adding the `title` and `content` fields, press N when asked if you want to add another field. Next, you should see: +If the summary of your fields looks like this, press Enter to confirm that it's correct. Next, you'll see: ::: output-block ```text @@ -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 Enter. (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 Y to create UI for it, then select the `TextArea` widget and press Enter. (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 Y 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 Enter, and use the arrow keys to select `ActionHash` as the field type. !!! dig-deeper Hashes and other identifiers @@ -599,7 +609,7 @@ You can check out the Core Concepts to dive a bit deeper into [how the distribut !!! -After press Enter, you should see: +After pressing Enter, you should see: ::: output-block ```text @@ -614,20 +624,25 @@ Next you will see: ::: output-block ```text ✔ Which entry type is this field referring to? +❯ Post ``` ::: -Press Enter to accept the suggested entry type `Post`. +Press Enter to accept the suggested entry type `Post`. Then press N to decline adding another field to the entry. -Next, you'll be asked to pick a field name. You can press Enter 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 N 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 Enter. Then at the next question, use the arrow keys to deselect `Update`, but leave `Delete` selected. It should look as follows: ::: output-block ```text @@ -637,7 +652,7 @@ Which CRUD functions should be scaffolded (SPACE to select/unselect, ENTER to co ``` ::: -Once that is done, press Enter to generate a delete function for the **`comment`** entry type. +Once that is done, press Enter to generate a delete function for the `comment` entry type. You should then see: @@ -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. diff --git a/src/pages/get-started/index.md b/src/pages/get-started/index.md index 34222f474..aad395191 100644 --- a/src/pages/get-started/index.md +++ b/src/pages/get-started/index.md @@ -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`: @@ -80,11 +80,11 @@ downloading 'https://holochain-ci.cachix.org/nar/.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.? ``` ::: diff --git a/src/pages/get-started/install-advanced.md b/src/pages/get-started/install-advanced.md index 56359a556..685ac2c35 100644 --- a/src/pages/get-started/install-advanced.md +++ b/src/pages/get-started/install-advanced.md @@ -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 @@ -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" +} ``` ::: @@ -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: diff --git a/src/pages/resources/upgrade/upgrade-holochain-0.3.md b/src/pages/resources/upgrade/upgrade-holochain-0.3.md index 2accb6443..ce1736299 100644 --- a/src/pages/resources/upgrade/upgrade-holochain-0.3.md +++ b/src/pages/resources/upgrade/upgrade-holochain-0.3.md @@ -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` @@ -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).