Fix wiab demo instructions by mohitrajain · Pull Request #60 · wireapp/wire-docs

mohitrajain · 2025-06-18T15:41:31Z

Change type

Documentation change
Build pipeline change
Submodule update
Deployment change

Basic information

THIS CHANGE REQUIRES A WIRE-DOCS RELEASE NOW

Testing

I ran/applied the changes myself, in a test environment.

Tracking

I mentioned this PR in Jira, OR I mentioned the Jira ticket in this PR.
I mentioned this PR in one of the issues attached to one of our repositories.

…lution

… old documents

sghosh23

Looks good and I left few comments

src/how-to/install/demo-wiab.md

sghosh23 · 2025-06-18T15:49:22Z

src/how-to/install/demo-wiab.md

+### What will be installed?
+
+- Wire-server (API)
+    - user accounts, authentication, conversations


Suggested change

- user accounts, authentication, conversations

- user accounts

- authentication

- conversations

they are core features and are clubbed together as basic APIs, carry forwarded from old documentation

That's okay, since we are listing then why grouping them together with comma that was my point

added them as core - user accounts, authentication, conversations

sghosh23 · 2025-06-18T15:55:15Z

src/how-to/install/demo-wiab.md

+- Email relay service i.e. demo-smtp
+- Group calling component i.e. coturn 
+- Ephemeral datastores in k8s
+- A cert-manager with `letsencrypt` as `issuser`. As an alternative to providing your own certificate, you may want to allow for automated certificate issuing through Let’s Encrypt. 


We do need to phrase this As an alternative to providing your own certificate, you may want to allow for automated certificate issuing through Let’s Encrypt. here on the list?

A good candidate to be in its own section such as Benefits of using letsencrypt

SSL/TLS certificates:
- a way to create SSL/TLS certificates for your domain name (to allow connecting via https://)
- To ease out the process of managing certs, we recommend using Let's Encrypt &
cert-manager

--- it is being talked in planning.md file which is starting point of this documentation:
https://github.com/wireapp/wire-docs/pull/60/files#diff-c73153d5e1b44f4727a457aae0f635e2922253659db169e31ca57b55609b5ff9R22

Yes, may be then we can omit this extra info regarding letsencrypt here as it feels like a repetition. When I am reading this i am asking this question to myself, is there a way to disallow the letsencrypt here and bring my own cert.

And the title says What will be installed? So I would just expect a list here and if the items on the list deserve description there can be another description section (that you already have in the planning to some extent) which can be linked to the list items.

Got the idea, removed the description and keeping it simple as
A cert-manager withletsencryptasissuser.

sghosh23 · 2025-06-18T15:56:54Z

src/how-to/install/demo-wiab.md

+- highly available k8s cluster
+
+### Diagram
+A demo installation will look a bit like this:


Suggested change

A demo installation will look a bit like this:

The flow diagram of the Demo setup

sghosh23 · 2025-06-18T16:03:32Z

src/how-to/install/demo-wiab.md

+
+This guide provides detailed instructions for deploying a Demo Wire-in-a-Box (WIAB) using Ansible on an Ubuntu 24.04 system. 
+
+The deployment process is structured into multiple blocks within the Ansible playbook, offering flexibility in execution. It is designed to configure a remote node, such as example.com (referred to as deploy_node), to install Wire with a custom domain, example.com (referred to as target_domain). 


is it required for the user to know how the ansible playbook is designed? If so please rephrase this sentence:
It is designed to configure a remote node, such as example.com (referred to as deploy_node), to install Wire with a custom domain, example.com (referred to as target_domain).
Is the example.com referred as both deploy_node and target_domain ?

yes, I am trying to give an idea on what to expect when running the ansible-playbook.

sghosh23 · 2025-06-18T16:06:46Z

src/how-to/install/demo-wiab.md

+
+These variables must be verified in the file [ansible/inventory/demo/host.yml](https://github.com/wireapp/wire-server-deploy/blob/master/ansible/inventory/demo/host.yml) before running the pipeline.
+
+Typically, the deployment process runs seamlessly without requiring any external flags. However, if needed, you have the option to skip certain tasks based on their conditional flags. 


Suggested change

Typically, the deployment process runs seamlessly without requiring any external flags. However, if needed, you have the option to skip certain tasks based on their conditional flags.

Typically, the deployment process runs seamlessly without requiring any external flags. However, if needed, you have the option to skip certain tasks by passing the conditional flags defined in the task.

sghosh23 · 2025-06-18T16:11:28Z

src/how-to/install/demo-wiab.md

+
+## Deployment requirements:
+  - Clone of [wire-server-repository](https://github.com/wireapp/wire-server-deploy)
+  - The inventory file [host.yml](https://github.com/wireapp/wire-server-deploy/blob/master/ansible/inventory/demo/host.yml) (post cloning the previous repo) to update and verify the following default variables:


(post cloning the previous repo) is confusing here. is it wire-server-repository repo? May be omit this part from the sentence. The link of the hosts.yaml takes to that file. Or can be rephrased as:

Suggested change

- The inventory file [host.yml](https://github.com/wireapp/wire-server-deploy/blob/master/ansible/inventory/demo/host.yml) (post cloning the previous repo) to update and verify the following default variables:

- The inventory file [host.yml](https://github.com/wireapp/wire-server-deploy/blob/master/ansible/inventory/demo/host.yml) in the wire-server-deploy needs to be verified and updated with the following default variables:

sghosh23 · 2025-06-18T16:11:58Z

src/how-to/install/demo-wiab.md

+## Deployment requirements:
+  - Clone of [wire-server-repository](https://github.com/wireapp/wire-server-deploy)
+  - The inventory file [host.yml](https://github.com/wireapp/wire-server-deploy/blob/master/ansible/inventory/demo/host.yml) (post cloning the previous repo) to update and verify the following default variables:
+    - ansible_host: aka **deploy_node** i.e. IP address or hostname of VM where Wire will be deployed (Mandatory)


Suggested change

- ansible_host: aka **deploy_node** i.e. IP address or hostname of VM where Wire will be deployed (Mandatory)

- ansible_host: aka **deploy_node** i.e. IP address or hostname of the VM where Wire will be deployed (Mandatory)

sghosh23 · 2025-06-18T16:14:29Z

src/how-to/install/demo-wiab.md

+### Ansible run selective tasks
+- You can use ^skip_ variables as environment variables to control the execution flow of the playbook. If these variables are passed, they will skip specific groups of tasks as explained in the [Deployment Flow](#deployment-flow) section. By default, if no variables are passed, all tasks will run in sequence.
+
+  In case of timeouts or any failures, you can skip tasks that have already been completed by passing the appropriate flags. For example, if the Wire artifact download task fails due to a timeout or disk space issue, you can skip the tasks that come before the Wire Artifact Download by using the following command:


Suggested change

In case of timeouts or any failures, you can skip tasks that have already been completed by passing the appropriate flags. For example, if the Wire artifact download task fails due to a timeout or disk space issue, you can skip the tasks that come before the Wire Artifact Download by using the following command:

In case of timeouts or other failures, you can skip tasks that have already been completed by passing the appropriate flags. For example, if the Wire artifact download task fails due to a timeout or a disk space issue, you can skip the preceding tasks by using the following command:

julialongtin · 2025-06-19T10:36:46Z

src/how-to/install/planning.md

+    - a way to create SSL/TLS certificates for your domain name (to allow connecting via https://)
+    - To ease out the process of managing certs, we recommend using [Let\'s Encrypt](https://letsencrypt.org/getting-started/) &
+[cert-manager](https://cert-manager.io/docs/tutorials/acme/http-validation/)
+    - Find a detailed explanation 


i think you missed here.

julialongtin · 2025-06-19T10:38:53Z

src/how-to/install/demo-wiab.md

+### What will not be installed?
+
+- notifications over native push notifications via [FCM](https://firebase.google.com/docs/cloud-messaging/)/[APNS](https://developer.apple.com/notifications/)
+- persistent datastores in k8s 


it k8s is redundant.

julialongtin · 2025-06-19T10:39:34Z

src/how-to/install/demo-wiab.md

+
+- notifications over native push notifications via [FCM](https://firebase.google.com/docs/cloud-messaging/)/[APNS](https://developer.apple.com/notifications/)
+- persistent datastores in k8s 
+- highly available k8s cluster


Suggested change

- highly available k8s cluster

- high availablity

julialongtin · 2025-06-19T10:42:42Z

src/how-to/install/demo-wiab.md

+For more detailed instructions on each task, please refer to the [Deployment Flow section](#deployment-flow).
+
+## Deployment requirements:
+  - Clone of [wire-server-repository](https://github.com/wireapp/wire-server-deploy)


Suggested change

- Clone of [wire-server-repository](https://github.com/wireapp/wire-server-deploy)

- Clone of [wire-server-deploy repository](https://github.com/wireapp/wire-server-deploy)

julialongtin · 2025-06-19T10:43:11Z

src/how-to/install/demo-wiab.md

+
+## Deployment requirements:
+  - Clone of [wire-server-repository](https://github.com/wireapp/wire-server-deploy)
+  - The inventory file [host.yml](https://github.com/wireapp/wire-server-deploy/blob/master/ansible/inventory/demo/host.yml) in the wire-server-deploy needs to  be verified and updated with the following default variables:


Suggested change

- The inventory file [host.yml](https://github.com/wireapp/wire-server-deploy/blob/master/ansible/inventory/demo/host.yml) in the wire-server-deploy needs to be verified and updated with the following default variables:

- The inventory file [host.yml](https://github.com/wireapp/wire-server-deploy/blob/master/ansible/inventory/demo/host.yml) in the wire-server-deploy needs to be verified and updated with the following default variables:

julialongtin · 2025-06-19T11:12:06Z

src/how-to/install/demo-wiab.md

+
+### Iptables behaviour
+
+- All the iptables rules are not persisted after reboots, but they can be regenerated by running the entire pipeline or restored from the `/home/ansible_user/wire-iptables-rules/rules_post_wire.v4` directory. Optionally, we can skip everything else when generating the rules again.


restored from the... so, just CDing to that directory restores iptables rules, eh? :)

yes, this is for the restart behavior, in case someone want to preserve the state post restart. They can use manual command or re-run the ansible-playbook to restore iptables rules.

mohitrajain added 4 commits June 17, 2025 19:54

WPB-17086: replace old demo docs and add new docs as per demo-wiab so…

a699ec6

…lution

WPB-17086: add support for mermaid diagrams, fix linking issues,clean…

2bc714f

… old documents

add codeowners to wire-docs

13f1b80

WPB-17086: fix broken links for demo k8s installation

500e70f

sghosh23 requested changes Jun 18, 2025

View reviewed changes

WPB-17086: fix suggested changes

b788a7b

julialongtin reviewed Jun 19, 2025

View reviewed changes

mohitrajain added 2 commits June 19, 2025 13:02

WPB-17086: fix suggested changes

66ce1dd

WPB-17086: fix suggested changes

004c782

julialongtin reviewed Jun 19, 2025

View reviewed changes

julialongtin approved these changes Jun 19, 2025

View reviewed changes

sghosh23 approved these changes Jun 19, 2025

View reviewed changes

mohitrajain merged commit 00327de into main Jun 19, 2025
2 checks passed

	A demo installation will look a bit like this:
	The flow diagram of the Demo setup


		This guide provides detailed instructions for deploying a Demo Wire-in-a-Box (WIAB) using Ansible on an Ubuntu 24.04 system.

		The deployment process is structured into multiple blocks within the Ansible playbook, offering flexibility in execution. It is designed to configure a remote node, such as example.com (referred to as deploy_node), to install Wire with a custom domain, example.com (referred to as target_domain).


		These variables must be verified in the file [ansible/inventory/demo/host.yml](https://github.com/wireapp/wire-server-deploy/blob/master/ansible/inventory/demo/host.yml) before running the pipeline.

		Typically, the deployment process runs seamlessly without requiring any external flags. However, if needed, you have the option to skip certain tasks based on their conditional flags.

	- The inventory file [host.yml](https://github.com/wireapp/wire-server-deploy/blob/master/ansible/inventory/demo/host.yml) (post cloning the previous repo) to update and verify the following default variables:
	- The inventory file [host.yml](https://github.com/wireapp/wire-server-deploy/blob/master/ansible/inventory/demo/host.yml) in the wire-server-deploy needs to be verified and updated with the following default variables:

	- ansible_host: aka deploy_node i.e. IP address or hostname of VM where Wire will be deployed (Mandatory)
	- ansible_host: aka deploy_node i.e. IP address or hostname of the VM where Wire will be deployed (Mandatory)

	In case of timeouts or any failures, you can skip tasks that have already been completed by passing the appropriate flags. For example, if the Wire artifact download task fails due to a timeout or disk space issue, you can skip the tasks that come before the Wire Artifact Download by using the following command:
	In case of timeouts or other failures, you can skip tasks that have already been completed by passing the appropriate flags. For example, if the Wire artifact download task fails due to a timeout or a disk space issue, you can skip the preceding tasks by using the following command:

	- Clone of [wire-server-repository](https://github.com/wireapp/wire-server-deploy)
	- Clone of [wire-server-deploy repository](https://github.com/wireapp/wire-server-deploy)


		### Iptables behaviour

		- All the iptables rules are not persisted after reboots, but they can be regenerated by running the entire pipeline or restored from the `/home/ansible_user/wire-iptables-rules/rules_post_wire.v4` directory. Optionally, we can skip everything else when generating the rules again.

Conversation

mohitrajain commented Jun 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Change type

Basic information

Testing

Tracking

Uh oh!

sghosh23 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mohitrajain commented Jun 18, 2025 •

edited

Loading