# Quickstart question: local self-hosted controller installation

**URL:** <https://openziti.discourse.group/t/quickstart-question-local-self-hosted-controller-installation/1343>\
**Category:** Support\
**Created:** [June 26, 2023, 2:04am UTC](https://openziti.discourse.group/t/quickstart-question-local-self-hosted-controller-installation/1343 "2023-06-26T02:04:47Z")\
**Posts on this page:** 20\
**Page:** 1

<div class="post-metadata">

**Author:** ![jfj](https://yyz2.discourse-cdn.com/free1/user_avatar/openziti.discourse.group/jfj/32/1042_2.png) [@jfj](https://openziti.discourse.group/u/jfj)\
**Post date:** [June 26, 2023, 2:04am UTC](https://openziti.discourse.group/t/quickstart-question-local-self-hosted-controller-installation/1343/1 "2023-06-26T02:04:47Z")

</div>

In the quickstart instructions [here](https://docs.openziti.io/docs/learn/quickstarts/network/local-no-docker), this set of statements exists:

* * *

> ### Verify the Controller is Running[​](https://docs.openziti.io/docs/learn/quickstarts/network/local-no-docker#verify-the-controller-is-running)
> 
> Assuming you have sourced the script, you will have an environment variable set named `$ZITI_EDGE_CONTROLLER_API`. After the controller has started, your controller should be listening at that hostname:port combination. You can see what your value is set to by running `echo $ZITI_EDGE_CTRL_ADVERTISED`. This variable defaults to: `$(hostname):1280`. Make sure the controller is on and listening and then start the edge router.
> 
> ```auto
> $ echo $ZITI_EDGE_CTRL_ADVERTISED
> My-Mac-mini.local.domain:1280
> 
> ```

* * *

I have sourced the script (although it would be helpful to be more specific in this statement and say exactly which script we are talking about, I can only assume it's the install script used above?) and this doesn't work. I neither have that `$ZITI_EDGE_CONTROLLER_API` variable nor do I get any response when trying to `echo $ZITI_EDGE_CTRL_ADVERTISED`. Has something maybe changed that needs to be reflected in the quickstart documentation to match new variable names, or is this a problem where I haven't sourced something correctly?

My controller is called `zctl`. I do have `ZITI_CTRL_EDGE_ADVERTISED_ADDRESS` and `ZITI_CTRL_ADVERTISED_PORT` in my printenv output and the zctl.env file. There isn't a single variable with "API" in it when you grep through the zctl.env file. I get a blank line when I try to echo as the instructions suggest:

```auto
jfj@zctl:~/.ziti/quickstart/zctl$ echo $ZITI_EDGE_CTRL_ADVERTISED

jfj@zctl:~/.ziti/quickstart/zctl$

```

Also, is there a better way to do some sort of test to see if the controller and edge router are up and running as expected, like a healthcheck?

Thanks,

John

---

<div class="post-metadata">

**Author:** ![TheLumberjack](https://yyz2.discourse-cdn.com/free1/user_avatar/openziti.discourse.group/thelumberjack/32/113_2.png) [@TheLumberjack](https://openziti.discourse.group/u/TheLumberjack)\
**Post date:** [June 26, 2023, 2:32am UTC](https://openziti.discourse.group/t/quickstart-question-local-self-hosted-controller-installation/1343/2 "2023-06-26T02:32:55Z")

</div>

> [@jfj](#):
>
> I have sourced the script (although it would be helpful to be more specific in this statement and say exactly which script we are talking about, I can only assume it’s the install script used above?)

Yah, good point. I'll update the doc to spell it out clearly. It should say "sourced the .env file created by the quickstart. The .env file is generally located at `$HOME/.ziti/quickstart/$(hostname)/$(hostname).env`. That's what it should say...

> [@jfj](#):
>
> Also, is there a better way to do some sort of test to see if the controller and edge router are up and running as expected, like a healthcheck?

There are [healthchecks from the controller](https://docs.openziti.io/docs/reference/configuration/controller#healthchecks) you can specify, but the quickstart doesn't enable them by default. Generally, I just check that the process is running and then curl to the API port to make sure it seems healthy. You can also portcheck using any port scanning tool. I will often use openssl s\_client to just probe the port but anything should work. I've actually not configured any router healthchecks but they are there as well [Router Configuration Reference | OpenZiti](https://docs.openziti.io/docs/reference/configuration/router/#healthChecks)

I'll often add this to my .bashrc file:

```auto
source $HOME/.ziti/quickstart/$(hostname)/$(hostname).env

```

---

<div class="post-metadata">

**Author:** ![TheLumberjack](https://yyz2.discourse-cdn.com/free1/user_avatar/openziti.discourse.group/thelumberjack/32/113_2.png) [@TheLumberjack](https://openziti.discourse.group/u/TheLumberjack)\
**Post date:** [June 26, 2023, 2:39am UTC](https://openziti.discourse.group/t/quickstart-question-local-self-hosted-controller-installation/1343/3 "2023-06-26T02:39:50Z")

</div>

Hmm. At the bottom of the page is a “Sourcing the env file” section… [Local - No Docker | OpenZiti](https://docs.openziti.io/docs/learn/quickstarts/network/local-no-docker/#sourcing-the-env-file)

That’s the missing sauce here, I’ll see if there’s some way to make that more clear higher up the page. Would that have helped?

---

<div class="post-metadata">

**Author:** ![jfj](https://yyz2.discourse-cdn.com/free1/user_avatar/openziti.discourse.group/jfj/32/1042_2.png) [@jfj](https://openziti.discourse.group/u/jfj)\
**Post date:** [June 26, 2023, 2:47am UTC](https://openziti.discourse.group/t/quickstart-question-local-self-hosted-controller-installation/1343/4 "2023-06-26T02:47:07Z")

</div>

Yeah, that is likely how I got it done but it would be helpful to have that sequentially up there as you suggested. Seems like the variables are not what is currently correct as well? I think that Verify the Controller is Running section needs correction or clarification overall.

Thanks for the notes on healthchecks.

---

<div class="post-metadata">

**Author:** ![TheLumberjack](https://yyz2.discourse-cdn.com/free1/user_avatar/openziti.discourse.group/thelumberjack/32/113_2.png) [@TheLumberjack](https://openziti.discourse.group/u/TheLumberjack)\
**Post date:** [June 26, 2023, 2:54am UTC](https://openziti.discourse.group/t/quickstart-question-local-self-hosted-controller-installation/1343/5 "2023-06-26T02:54:46Z")

</div>

I updated it just now and I have a PR change up to fix the "echo/curl" section. Now it reads:

### Verify the Controller is Running[​](https://docs.openziti.io/docs/learn/quickstarts/network/local-no-docker/#verify-the-controller-is-running)

After running `expressInstall`, you will have environment variables set named `ZITI_CTRL_EDGE_ADVERTISED_ADDRESS` and `ZITI_CTRL_EDGE_ADVERTISED_PORT`. After the controller has started, your controller should be listening at that address:port combination. (Note, if you do not have these environment variables, you've probably closed your shell and opened it up again. You can get the environment variables by sourcing the ".env" file. [See the section at the bottom of the page](https://docs.openziti.io/docs/learn/quickstarts/network/local-no-docker/#sourcing-the-env-file) for details)

---

<div class="post-metadata">

**Author:** ![jfj](https://yyz2.discourse-cdn.com/free1/user_avatar/openziti.discourse.group/jfj/32/1042_2.png) [@jfj](https://openziti.discourse.group/u/jfj)\
**Post date:** [June 26, 2023, 2:57am UTC](https://openziti.discourse.group/t/quickstart-question-local-self-hosted-controller-installation/1343/6 "2023-06-26T02:57:01Z")

</div>

That’s excellent! Thanks! I think it will be easier for folks like me to follow this way.

---

<div class="post-metadata">

**Author:** ![jfj](https://yyz2.discourse-cdn.com/free1/user_avatar/openziti.discourse.group/jfj/32/1042_2.png) [@jfj](https://openziti.discourse.group/u/jfj)\
**Post date:** [July 5, 2023, 1:58am UTC](https://openziti.discourse.group/t/quickstart-question-local-self-hosted-controller-installation/1343/7 "2023-07-05T01:58:41Z")

</div>

@TheLumberjack Hi, sorry to still be struggling here but I need some more help or advice on whether I just start the quickstart all over again. When I left this build a few days ago, I had a controller and router running from my quickstart and I had successfully installed and configured ZAC with the ability to log into the web UI for ZAC. I thought everything was set for me to start configuring identities and services.

When I returned to this host today I did some basic maintenance updates, as I tend to do, and this included a kernel update which required a reboot. Upon reboot I of course tried to verify that the ziti controller and router and ZAC were all up and running. None of them appear to be, so I assumed that I hadn’t properly succeeded in getting the systemd stuff configured or perhaps was missing some shell or environment variables, etc. I’ve checked through all of these, and I also followed your advice and even added  
`export PATH=$PATH:/home/jfj/.ziti/quickstart/zctl/ziti-bin/ziti-v0.28.4` and  
`source $HOME/.ziti/quickstart/zctl/zctl.env` to my .bashrc, and I can verify that they’re loading correctly:

```auto
jfj@zctl:~$ echo $ZITI_HOME
/home/jfj/.ziti/quickstart/zctl

```

This is what happens at the moment:

```auto
jfj@zctl:~$ startRouter
startRouter: command not found
jfj@zctl:~$ startController
startController: command not found

```

Same results when I tried to go back and make sure that I had the auto restart using systemd configured:

```auto
jfj@zctl:~$ cd $ZITI_HOME
jfj@zctl:~/.ziti/quickstart/zctl$ createControllerSystemdFile
createControllerSystemdFile: command not found

```

etc with the rest of the items here: [Host OpenZiti Anywhere | OpenZiti](https://openziti.io/docs/learn/quickstarts/network/hosted#systemd)

Interestingly, this also happens:

```auto
jfj@zctl:~/.ziti/quickstart/zctl$ curl "${ZITI_CTRL_EDGE_ADVERTISED_ADDRESS}:${ZITI_CTRL_EDGE_ADVERTISED_PORT}"
curl: (7) Failed to connect to zctl port 1280 after 0 ms: Connection refused

```

So apparently those variables are properly showing port 1280 but of course nothing is started.

What’s my best course of action here- should I follow the instructions to reset and start over?

Thanks.

-John

---

<div class="post-metadata">

**Author:** ![jfj](https://yyz2.discourse-cdn.com/free1/user_avatar/openziti.discourse.group/jfj/32/1042_2.png) [@jfj](https://openziti.discourse.group/u/jfj)\
**Post date:** [July 5, 2023, 2:15am UTC](https://openziti.discourse.group/t/quickstart-question-local-self-hosted-controller-installation/1343/8 "2023-07-05T02:15:26Z")

</div>

@TheLumberjack additional note:

I went to verify that there is indeed a ziti-controller.service and a ziti-router.service file in /etc/systemd/system. They are there and contents look correct.

Here is the output from checking status:

```auto
jfj@zctl:/etc/systemd/system$ sudo systemctl -q status ziti-controller --lines=0 --no-pager
● ziti-controller.service - Ziti Controller
     Loaded: loaded (/etc/systemd/system/ziti-controller.service; enabled; vendor preset: enabled)
     Active: activating (auto-restart) (Result: exit-code) since Wed 2023-07-05 02:12:41 UTC; 144ms ago
    Process: 8150 ExecStart=/home/jfj/.ziti/quickstart/zctl/ziti-bin/ziti-v0.28.1/ziti controller run /home/jfj/.ziti/quickstart/zctl/zctl.yaml (code=exited, status=203/EXEC)
   Main PID: 8150 (code=exited, status=203/EXEC)
        CPU: 1ms

```

---

<div class="post-metadata">

**Author:** ![TheLumberjack](https://yyz2.discourse-cdn.com/free1/user_avatar/openziti.discourse.group/thelumberjack/32/113_2.png) [@TheLumberjack](https://openziti.discourse.group/u/TheLumberjack)\
**Post date:** [July 5, 2023, 2:16am UTC](https://openziti.discourse.group/t/quickstart-question-local-self-hosted-controller-installation/1343/9 "2023-07-05T02:16:40Z")

</div>

> [@jfj](#):
>
> None of them appear to be, so I assumed that I hadn’t properly succeeded in getting the systemd stuff configured or perhaps was missing some shell or environment variables, etc.

Yeah that's what I would expect. I can see you're just a bit confused with respect to systemd vs the helper scripts functions startController/Router. if you "enabled" systemd, then you should have had the services start on reboot and you check that using these commands

```auto
sudo systemctl -q status ziti-controller --lines=0 --no-pager
sudo systemctl -q status ziti-router --lines=0 --no-pager

```

Those should show you the process running. If not you'll want to look to the logs using journalctl for hints as to what happened...

I'll finish this reply because I see you found the status

---

<div class="post-metadata">

**Author:** ![jfj](https://yyz2.discourse-cdn.com/free1/user_avatar/openziti.discourse.group/jfj/32/1042_2.png) [@jfj](https://openziti.discourse.group/u/jfj)\
**Post date:** [July 5, 2023, 2:17am UTC](https://openziti.discourse.group/t/quickstart-question-local-self-hosted-controller-installation/1343/10 "2023-07-05T02:17:39Z")

</div>

Yes, I’m on the same path here apparently. Router also shows same status.

---

<div class="post-metadata">

**Author:** ![TheLumberjack](https://yyz2.discourse-cdn.com/free1/user_avatar/openziti.discourse.group/thelumberjack/32/113_2.png) [@TheLumberjack](https://openziti.discourse.group/u/TheLumberjack)\
**Post date:** [July 5, 2023, 2:17am UTC](https://openziti.discourse.group/t/quickstart-question-local-self-hosted-controller-installation/1343/11 "2023-07-05T02:17:48Z")

</div>

You’ll want to look to the controller logs to see what’s happening. I definitely wouldn’t have expected an issue with a patch type of update. Let’s see what the logs show us

---

<div class="post-metadata">

**Author:** ![jfj](https://yyz2.discourse-cdn.com/free1/user_avatar/openziti.discourse.group/jfj/32/1042_2.png) [@jfj](https://openziti.discourse.group/u/jfj)\
**Post date:** [July 5, 2023, 2:19am UTC](https://openziti.discourse.group/t/quickstart-question-local-self-hosted-controller-installation/1343/12 "2023-07-05T02:19:27Z")

</div>

I’ll start digging- in the meantime, can you help me out with understanding the helper script functions which must not be correctly loaded for me? A way to troubleshoot or fix that?

---

<div class="post-metadata">

**Author:** ![TheLumberjack](https://yyz2.discourse-cdn.com/free1/user_avatar/openziti.discourse.group/thelumberjack/32/113_2.png) [@TheLumberjack](https://openziti.discourse.group/u/TheLumberjack)\
**Post date:** [July 5, 2023, 2:23am UTC](https://openziti.discourse.group/t/quickstart-question-local-self-hosted-controller-installation/1343/13 "2023-07-05T02:23:43Z")

</div>

Sure. I just had to explain it to someone else just tonight so I filled an issue to clarify.

> [@Quickstart Authentication Req Failed - Local No Docker](https://openziti.discourse.group/t/quickstart-authentication-req-failed-local-no-docker/1345/6):
>
> These are functions you get when sourcing [ziti-cli-functions](https://get.openziti.io/quick/ziti-cli-functions.sh). We really need to make this more clear as it's a common stumbling block. Those ZAC errors are annoying but not important. It's related to the session of your browser. You'll see those. @jeremy.tellier it's probably worth tracking those down? Most definitely! smile I think I addressed the "didn't work" comment above. Hope that helps

These are functions you get when sourcing ziti-cli-functions. They simply run the binary directly. They are just functions that do exactly what the systemd unit files do but you're running them directly

---

<div class="post-metadata">

**Author:** ![jfj](https://yyz2.discourse-cdn.com/free1/user_avatar/openziti.discourse.group/jfj/32/1042_2.png) [@jfj](https://openziti.discourse.group/u/jfj)\
**Post date:** [July 5, 2023, 2:26am UTC](https://openziti.discourse.group/t/quickstart-question-local-self-hosted-controller-installation/1343/14 "2023-07-05T02:26:13Z")

</div>

OK, so this is interesting.

```auto
jfj@zctl:/etc/systemd/system$ tail /var/log/syslog
Jul 5 02:19:10 zctl systemd[8533]: ziti-controller.service: Failed to locate executable /home/jfj/.ziti/quickstart/zctl/ziti-bin/ziti-v0.28.1/ziti: No such file or directory
Jul 5 02:19:10 zctl systemd[8533]: ziti-controller.service: Failed at step EXEC spawning /home/jfj/.ziti/quickstart/zctl/ziti-bin/ziti-v0.28.1/ziti: No such file or directory
Jul 5 02:19:10 zctl systemd[1]: Stopped Ziti Router for zctl-edge-router.
Jul 5 02:19:10 zctl systemd[1]: Started Ziti Router for zctl-edge-router.
Jul 5 02:19:10 zctl systemd[8534]: ziti-router.service: Failed to locate executable /home/jfj/.ziti/quickstart/zctl/ziti-bin/ziti-v0.28.1/ziti: No such file or directory
Jul 5 02:19:10 zctl systemd[8534]: ziti-router.service: Failed at step EXEC spawning /home/jfj/.ziti/quickstart/zctl/ziti-bin/ziti-v0.28.1/ziti: No such file or directory
Jul 5 02:19:10 zctl systemd[1]: ziti-controller.service: Main process exited, code=exited, status=203/EXEC
Jul 5 02:19:10 zctl systemd[1]: ziti-controller.service: Failed with result 'exit-code'.
Jul 5 02:19:10 zctl systemd[1]: ziti-router.service: Main process exited, code=exited, status=203/EXEC
Jul 5 02:19:10 zctl systemd[1]: ziti-router.service: Failed with result 'exit-code'.

```

I can immediately see the obvious problem, although I’m not sure how this occurred. Maybe I did a previous quickstart run with a different earlier version which wrote these .service files and they’re pointing to the wrong directory now. I’m at v0.28.4 and the executable directory structure reflects that. I can’t use the `createControllerSystemdFile` so something isn’t loaded here and if I can get the helper scripts working I should be able to fix this, but I don’t know how to do that other than start over?

---

<div class="post-metadata">

**Author:** ![TheLumberjack](https://yyz2.discourse-cdn.com/free1/user_avatar/openziti.discourse.group/thelumberjack/32/113_2.png) [@TheLumberjack](https://openziti.discourse.group/u/TheLumberjack)\
**Post date:** [July 5, 2023, 2:30am UTC](https://openziti.discourse.group/t/quickstart-question-local-self-hosted-controller-installation/1343/15 "2023-07-05T02:30:26Z")

</div>

> [@jfj](#):
>
> createControllerSystemdFile

This is also from the ziti-cli-functions.sh script. You don't need to start over entirely, just don't run the final function "expressInstall".

So just source the file like this:

```auto
source /dev/stdin <<< "$(wget -qO- https://get.openziti.io/quick/ziti-cli-functions.sh)"

```

(Note the lack of expressInstall)

That will get the helper functions into your shell. Does the folder shown actually exist and is the ziti cli in there? Strange...

---

<div class="post-metadata">

**Author:** ![jfj](https://yyz2.discourse-cdn.com/free1/user_avatar/openziti.discourse.group/jfj/32/1042_2.png) [@jfj](https://openziti.discourse.group/u/jfj)\
**Post date:** [July 5, 2023, 2:34am UTC](https://openziti.discourse.group/t/quickstart-question-local-self-hosted-controller-installation/1343/16 "2023-07-05T02:34:46Z")

</div>

Perfect, thanks for explaining that. The folder doesn’t exist:

```auto
jfj@zctl:~/.ziti/quickstart/zctl/ziti-bin$ ls -la
total 12
drwxrwxr-x 3 jfj jfj 4096 Jun 25 21:23 .
drwxrwxr-x 7 jfj jfj 4096 Jun 25 23:28 ..
drwxrwxr-x 2 jfj jfj 4096 Jun 25 21:23 ziti-v0.28.4

```

I’m definitely most likely to believe this was something I did that I’m not remembering- like running the script a second time days later and maybe the older version wrote those, but I’ll look at the script to make sure there isn’t some absolute reference to that other path leftover from somewhere.

---

<div class="post-metadata">

**Author:** ![TheLumberjack](https://yyz2.discourse-cdn.com/free1/user_avatar/openziti.discourse.group/thelumberjack/32/113_2.png) [@TheLumberjack](https://openziti.discourse.group/u/TheLumberjack)\
**Post date:** [July 5, 2023, 2:35am UTC](https://openziti.discourse.group/t/quickstart-question-local-self-hosted-controller-installation/1343/17 "2023-07-05T02:35:51Z")

</div>

You probably want to run ‘getZiti’. It’ll fetch the binaries for you… Or just download and put them into place and I expect it’ll start back up. (getZiti is another helper functions)

---

<div class="post-metadata">

**Author:** ![jfj](https://yyz2.discourse-cdn.com/free1/user_avatar/openziti.discourse.group/jfj/32/1042_2.png) [@jfj](https://openziti.discourse.group/u/jfj)\
**Post date:** [July 5, 2023, 2:39am UTC](https://openziti.discourse.group/t/quickstart-question-local-self-hosted-controller-installation/1343/18 "2023-07-05T02:39:22Z")

</div>

> [@TheLumberjack](#):
>
> `source /dev/stdin <<< "$(wget -qO- https://get.openziti.io/quick/ziti-cli-functions.sh)"`

OK great, thanks. Should I also add sourcing those files to my .bashrc to keep them "sticky" so I can always use them, I assume, as a best practice?

---

<div class="post-metadata">

**Author:** ![jfj](https://yyz2.discourse-cdn.com/free1/user_avatar/openziti.discourse.group/jfj/32/1042_2.png) [@jfj](https://openziti.discourse.group/u/jfj)\
**Post date:** [July 5, 2023, 2:40am UTC](https://openziti.discourse.group/t/quickstart-question-local-self-hosted-controller-installation/1343/19 "2023-07-05T02:40:08Z")

</div>

Well, obviously that wouldn’t be a security best practice lol 🤦‍♂️

---

<div class="post-metadata">

**Author:** ![TheLumberjack](https://yyz2.discourse-cdn.com/free1/user_avatar/openziti.discourse.group/thelumberjack/32/113_2.png) [@TheLumberjack](https://openziti.discourse.group/u/TheLumberjack)\
**Post date:** [July 5, 2023, 2:46am UTC](https://openziti.discourse.group/t/quickstart-question-local-self-hosted-controller-installation/1343/20 "2023-07-05T02:46:48Z")

</div>

Technically you should probably download the file, read it and make sure it’s safe… Yeah. 😆

I find once you get through this learning phase you’ll probably rarely/never need those functions again… I personally always source the .env file making logging in easier. But I nearly never need these functions and I just source them if I need to

[Next page](https://openziti.discourse.group/t/quickstart-question-local-self-hosted-controller-installation/1343.md?page=2)