This is the Frequently Asked Questions section.
Navigate it quickly by using the Table of Contents or the search bar; searching is easy, and makes you look cool.. Just saying.
Note: VivumLab does assume some prior knowledge on behalf of the user, if you do not have this knowledge using VivumLab will not be impossible but you may find it hard to troubleshoot any issues you may have.
We assume you know or understand the basics of:
- your server operating system (where VivumLab will store your services)
- your client operating system (the computer that you use VivumLab from)
- Access via SSH
- Pointing your domain ('A' record) to the required IP address
No, and as long as it remains open source, it never will. If you paid money for this service, get your money back.
HomeLabOS is a great project, and while we are very similar, we differ in some core values and (general) project direction. VivumLab is an alternative to HomeLabOS, not a replacement; We would like to suggest that you test both projects and see which one suits you; everyone is different and deserves the freedom to choose. If you decide to stick with VivumLab, then Welcome to the community; lets do some amazing things together.
We just want to start by saying open source is very important, a free (as in freedom) internet, is something worth protecting. That being said, you may have noticed that some of the services we provide are open source, and some are not; while VivumLab advocates for and prefers open source projects, we undestand that sometimes a closed source project is required or desired by the user. The least we can do is keep VivumLab open source and free for further generations to come.
VivumLab supports deploying to Ubuntu, Debian and CentOS based systems; since RaspberryPI OS is based on Debian, VivumLab should work. While it is theortically possible to deploy to other systems with some code changes, supporting niche or closed source systems are not a great priority for VivumLab. Changes to support such systems are welcome, should a developer wish to provide the code and support for the system.
Currently, VivumLab can be run from a Linux PC, a Macintosh PC and should support Windows (untested as of now). This is possible because we run everything from inside of a docker container. See Docker for more information about docker.
- If you ping your domain, do you get the IP you expect?
- If not you have DNS issues. Get those resolved before moving on.
- If you ping your subdomain, do you get the IP you expect?
- If not you have DNS issues. You probably don't have a wildcard set up.
- If you're still having issues with your domain, contact your domain registrar (whom you purchased your domain from); there is a good chance that they have their own documentation regarding this.
- Does the IP you expect actually lead to port 80 on your server?
- You may need to set up port forwarding on your router, unblock some ports on your modem, or contact your ISP to see if they are being blocked. If these aren't an option for you, try the bastion host set up.
- Does the domain you're trying to access match what is listed in the Traefik dashboard?
- If you don't see your domain under the 'HTTP' section in Traefik, then you have something configured wrong.
- Are your services running?
systemctl status SERVICENAMEon the server.
systemctl status jellyfin
- Are your services listed in the Traefik dashboard?
- Check http://127.0.0.1:8181/ (only available if traefik expose internally is set to true)
If you have followed these instructions and you are STILL having issues, ask in the VivumLab Zulip chat or open an issue on Github. !!! Note: The documentation for VivumLab represents hours of work by the developers. Do not be offended if you ask a question, and are redirected back to the documentation. It is entirely for your own benefit; no one elses'.
If you're up and running, but accessing the server returns a 404, check the Traefik dashboard.
Each service under the
Http page has a section. The hostname inside
Host() in the rule column is the hostname that Traefik is listening to for that particular service. You need to be able to ping that hostname from your computer, and you should get back the IP address of your server. Once that is the case, accessing the domain name in a browser should load the respective service.
Traefik serves based on domain names, not IP addresses. It has to know what service you want to return. You need to be able to access the domain name in order for Traefik to serve the correct service.
If you can't even access the dashboard at http://127.0.0.1:8181, check the status of the VivumLab service to give you some insight into what the issue is. e.g:
systemctl status vivumlab
docker ps | grep traefik
which should provide similar output to this:
8f00f6b3cdb6 traefik "/traefik" 13 hours ago Up 13 hours 0.0.0.0:80->80/tcp, 0.0.0.0:443->443/tcp, 0.0.0.0:8181->8080/tcp vivumlab_traefik_1
If there is no obvious issue, contact the community on Zulip
If you don't see the services listed in the Traefik dash, or if Traefik returns a page that just says
Bad Gateway, that usually means DNS and everything is correct, but the service itself is having problems.
SSH into the server and run
systemctl status SERVICE_NAME
systemctl status jellyfin
This should show you any Docker logs relevant to that service. In the case of a service running multiple containers, you may want more detail from a specific container.
Find the container name with
docker ps | grep SERVICENAME then access the logs with
docker logs -f --tail 500 CONTAINERNAME.
docker ps | grep jellyfinand:
docker logs -f --tail 500 jellyfin_jellyfin_1
Traefik generates SSL certs via LetsEncrypt, and LetsEncrypt has rate limiting. So it may take several days before all of your services get valid SSL certs generated for them. You can tail the logs of the traefik container (as mentioned previously) to see the status of its generation.
vlab commands throw Connection timed out#
vlab dev set --config-key wait_for_connection --value true, this enables the tasks to test for 600 seconds if a connection to the server can be stablished.
vlab command throws a docker related error#
Make sure VivumLab successfully installed docker on the server. If its not installed, try installing it manually.
Make sure you are running the latest docker and docker compose on both your client and server. The versions installed via your Operating Systems' package manager may be outdated; here is some information to help you get started. VivumLab may attempt to do this for you, in a future release.
Check VivumLab status on the server and make sure it is loaded and active.
systemctl status vivumlab
Make sure the admin user specified during
vlab configis created.
If the user isn't listed, run the following commands (on the server) to make one and add it to the sudo and docker groups.
sudo adduser <username>
sudo usermod -aG sudo <username>
sudo usermod -aG docker <username>
Stops the specified service from serving any access over an unsecure (HTTP) connection.
Most services deployed with VivumLab will redirect wherever possible, to a secure (HTTPS) connection without any intervention from the user. As such, this option is available only for unique cases. Most users will never have to use this.
Allows third party services to assume control of authentication for a specified service.
Some, if not most services deployed with VivumLab, make use of their own authentication system to protect the information stored therein; you may need to enter a username/email and password to access it. This option allows Authelia to control authentication for services that otherwise may not have any.
For example, the dashboard used for VivumLab is called SUI, and typical does not have authentication. Setting auth to True, allows SUI to be protected. This is completely optional, but available if you want it.
Sets a different, custom domain.
All services (by default) are served on
servicename.domain.tld; assuming that you are serving VivumLab services on the domain 'magicfinger.com', and you were deploying the awesome open source media center 'Jellyfin', the default URL would look like this:
The 'domain' option for Jellyfin can be changed if the user desires Jellyfin to be served on another domain, eg. magictoe.com. VivumLab allows the change of the sitename, but no subdomains (future releases may support this). In this example, once the domain option is changed Jellyfin will be served on
The domain option is also useful if the user wants a specific service served on the top level domain, and not on it's default subdomain. Using the same example, if the domain option is set to
magicfinger.com, Jellyfin will be served on
magicfinger.com, instead of the default
Sets a different, custom subdomain.
Similarly to the domain option, the subdomain option allows the user to customise the subdomain for their service. Unlike the domain, it is simple, not complex. The subdomain option defaults to the servicename; using the previous example, the default subdomain is
jellyfin, making the default URL
Changing the subdomain option to
media would allow jellyfin to be reached on
Sets the image version of the docker image used.
VivumLab acknowledges that some versions of specific softwares may be more desirable than others; this option allows the user to specify another version. Please note that the default value is the version that VivumLab has been tested with, and has shown to work the best at the time of testing. if the user decides to change the version, VivumLab can not guarantee that the adjusted version will work.
config/encrypted.yml file. If it's encrypted just run
vlab config decrypt --dev, and attempt to access it again.
Is it OK to manually edit my
Yes, but note that isn't specifically necessary to edit the
config/ files directly, or worry about where the config values are.
vlab service show -s jellyfin will access the variable correctly regardless of which config file it lives in.
vlab dev set --dev --config-key <key> --value <value> will set the variable correctly,regardless of which config file
vlab dev set --dev --config-key jellyfin.domain --value magicfinger.com
You may be trying to run AMD code on ARM infrastructure.
Make sure you have set
arm to True.
You can set it with
vlab dev set --dev --config-key arm --value True,
or you can edit your config file, run
vlab config edit_raw --dev (not recommended for none developers).
On your server, run
systemctl status servicename, as root, or
sudo systemctl status servicename as another user.
systemctl status jellyfin
Unit servicename.service could not be found.#
The service was not deployed.
Enable the desired service. eg.
vlab service setup --service SERVICENAME
vlab config edit_raw --dev (not recommended for none developers), and set
enable to true for the respective service. e.g:
jellyfin: enable: True
You can use Vivumlab fully inside your network, without an external domain. Simply make up a domain that ends in
.local and enter that as your domain in
host_vars/myserver, for example
myvivumlab.local will work just fine, but there are some small changes that you will need to make.
VivumLab will generate a file called
vivumlab_hostson the server, located in the VivumLab root folder; You can use the entries in this file to add to your computer's hosts override file (
/etc/hosts on *nix based OS'), or to map on your router or DNS server as DNS overrides.
Ultimately, if you used the example fake domain given above and you enabled the Jellyfin service, you can access it at
jellyfin.myvivumlab.local once you have your DNS overrides set up.
Yes, but you shouldn't. A quick Google search will return some options for you; however VivumLab does not officially support it.
Older version of Raspberry Pi OS (previously Raspbian) are 32 bit and in theory it is possible to use this OS; but again, VivumLab does not officially support it.