Differences

This shows you the differences between two versions of the page.

--- blocks:server:virtualized [2022-10-20 09:13] – Added note on certbot renew --dry-run admin
+++ blocks:server:virtualized [2025-09-05 20:10] (current) – Deleted admin
@@ Line 1: / Line 1: @@
-======Virtualized Server Image======
-While the full Linux-based server image can be installed on a virtual machine, it is not specifically designed for that purpose. Installations that run Blocks in a virtualized environment often have different priorities than those using a stand-alone server. Many of the features included in the full server Linux image are typically managed by other parts of the infrastructure in a virtualized environment.
-:!: This is an advanced guide. If you don't feel at home in a Linux terminal window, you should probably not follow it.
-===Minimal Server OS===
-The full Linux-based server runs an enhanced desktop version of Ubuntu, including a user friendly window-and-mouse based desktop environment. That's suitable for users that prefer such a desktop environment for managing their server. In contrast, the virtual server image discussed here runs on Debian, which is essentially the same operating system core, but a pure server-version, without any desktop environment. Thus, all system management and maintenance must be done from the command line.
-===No Webmin interface===
-The user-friendly, web-based //webmin// frontend is not included. While you may install webmin also on a virtual server, the assumption is that you likely prefer configuring the server directly, using the various configuration files traditionally used by server administrators.
-===No DHCP server===
-There's no pre-configured DHCP server. When used as part of a virtualized server infrastructure, you likely already have a DHCP server in your system, and don't want the Blocks server to act as one.
-===No DNS server===
-The same applies for the DNS server. While the software is included also in the virtualized server image, it has not been pre-configured and is not enabled.
-=====Virtual Environment=====
-This image is designed to be used in a virtualized environment. It is distributed as an [[https://pixilab.se/outgoing/blocks/virtualized/Blocks6-Debian10.ova|OVA file]], compatible with most virtual hosts from VMWare, Oracle, Synology and QNAP. The image is based on Debian 10, and includes Blocks software and all components required to run Blocks. For testing purposes, you can use one of the following:
-  * Oracle [[https://www.virtualbox.org/wiki/Downloads|VirtualBox]] – a free virtual machine available for most operating systems
-  * VMWare's free "Workstation Player" as well as their popular "VMWare Fusion".
-After importing the OVA file into your virtualizer of choice, start it up and wait for the login screen to appear.
-=====Users and Passwords=====
-For full system access, log in with the user name **root**, with password //pixi//. This **root** user can do anything without restrictions, so be careful. Use this user for for system software installation, upgrades, etc requiring super-user privileges. The password can be changed using the //passwd// command.
-User name **blocks**, with default password //PixiServer!// is the account under which the Blocks server is run. This user has limited rights, and can not use the sudo command to escalate its privileges (you can, however, use the //su// command to switch to the root user). The password can be changed by the root user using the //passwd blocks// command.
-=====Network Configuration=====
-On the Host computer, running VirtualBox (or other preferred virtualizer), add a Bridged adapter as the primary one. You may need to shut down the Blocks server while changing network settings.
-====Guest Linux OS terminal window====
-Find the network interface name and verify connectivity.
-  * Use the command //ip addr// to see all network interfaces with their names. Ignore the //lo// loopback interface.
-  * The name is typically something like //enp0s3//.
-  * If the interface is already UP, and you have internet access, you're done
-  * Verify internet access by using the command //ping 1.1.1.1//, that should show the turn-around time in mS repeatedly if OK.
-===Verify/Add Network Adapter Settings===
-If you didn't automatically get network access, you need to configure networking inside the virtual Blocks server. Settings are specified in the **/etc/network/interface.d** directory.
-If required, add a file there and name it //primary// (although the actual file name isn't important). Enter the following data into the file. You can do so using the simple terminal text editor //nano//.
-<code>
-auto enp0s3
-allow-hotplug enp0s3
-iface enp0s3 inet dhcp
-</code>
-Use the actual name of your interface in the file instead of //enp0s3//, if different.
-These settings result in a dynamic address, suitable for testing purposes. Since the interface is bridged, the virtual machine will get a network address from your local network, assuming there's a DHCP server. For real server purposes, you should change this file to assign a static address instead (see below).
-:!: Do not use a wifi network interface, since that will typically not provide a dynamic address to the virtual machine.
-Alternatively, to use a fixed IP address instead, edit the //primary// file discussed above to read something like this (specifying IP addresses and subnet width as appropriate for your network):
-<code>
-auto enp0s3
-allow-hotplug enp0s3
-iface enp0s3 inet static
-    address 192.168.0.31/24
-    gateway 192.168.0.1
-    dns-nameservers 1.1.1.1 8.8.8.8
-</code>
-After making changes, restart the virtual machine using //reboot now// or merely restart the networking stack by
-//systemctl restart networking//.
-=====License Access=====
-Blocks server software requires a license to be operational. Either connect a physical license key to a USB port or request a cloud-based license (requires internet access). A physical license key can be accessed either directly from a USB port attached to the virtual machine or over the local network.
-====Network Access from Host Computer====
-This method provides access to the license key over the network. Assuming both the guest and host operating systems are on the same network (which they will be when using a network adapter in bridge mode), a license key connected to the host computer can be accessed. This assumes network access is allowed in the license keys's settings (more on this below). Thus, the physical USB key can be connected to the host computer and will then be automatically found by Blocks.
-=== Host operating system ===
-Verify or adjust the following license key settings in your host computer
-  * Open the CodeMeter Control Center.
-  * Click the WebAdmin button, and wait for the web UI to appear.
-  * Select Configuration > Server.
-  * Under Network Server, select Enable.
-  * Click Apply.
-=== Guest operating system ===
-The CodeMeter software has been pre-installed, and configured to look for the license on the local network. To verify accesibility:
-  * Start the virtual machine.
-  * Once up, use the command //cmu --list-server --list-content//.
-  * This should show your server's IP address and license information. Look for the text "102977"
-==== Connecting the USB License Key to Another Computer ====
-In the example above, the license key is physically connected to the host computer, and then accessed over the (host-computer internal) "network". If you can't connect the license key to the host computer for some reason, you can instead connect it to another computer on the same subnet, and it will be found automatically by Blocks. Alternatively, use a cloud-based license (requires internet access).
-====Direct USB Access====
-If you have physical access to the computer running the virtualizer, you may prefer to connect the license key directly to this computer, and make the USB port accessible to the guest OS.
-=== Host computer ===
-  * Connect the license key. The key must be physically connected to a USB port on the host computer.
-  * Do NOT install the CodeMeter driver/software (or disable it if already installed).
-:!: The host computer must NOT run the CodeMeter software, since only one driver may access the physical key at a time, and in this case that's is the driver inside the virtual machine.
-===VirtualBox settings ===
-  * Select your guest OS in the list on the left hand side
-  * Select its Details settings pane
-  * Click USB
-  * Make sure "Enable USB Controller" is selected
-  * Add a "USB Device Filter" using the + button to the right
-  * Select your CodeMeter device
-To verify license key accesibility:
-  * Start the virtual machine.
-  * Once up, use the command //cmu -x//.
-  * This should show the details of your license key. Look for the text "102977".
-=====Blocks Configuration=====
-There's no [[blocks:server_configuration_file|configuration file]] included for Blocks in the VM image. This means that Blocks defaults to HTTP over port 8080. Add a configuration file if you need to adjust Blocks' server settings. Note that since Blocks runs under a limited user account, ports below 1024 (thus including the default HTTP port 80) can't be directly specified in the configuration file.
-=====Reverse Proxy Configuration=====
-The server image includes [[http://nginx.org|nginx]], acting as a reverse proxy in front of Blocks. Out of the box, it provides the following functionality:
-===Port Remapping===
-The reverse proxy re-maps ports as the traffic flows through it, thereby exposing HTTP to the outside world on the standard port 80, internally passing it on to Blocks on port 8080. Thus, when accessing Blocks from outside the virtual machine, you don't need to specify any port number.
-===Serving of Static Files===
-It serves all static files (those under /public), rather than passing those requests on to Blocks. Offloading such work leaves more headroom in Blocks for dealing with its more advanced functions.
-====HTTPS, Domain name and Certificate====
-The nginx reverse proxy can also manage a secure HTTPS connection, thus offloading also the work of encryption and decryption from Blocks. HTTPS is increasingly a requirement for many advanced web features. This applies also to Blocks, which is entirely web based. For instance, the Camera, QR Scanner and Locator (when using QR Code or GPS) block types may have limited or no functionality unless  a secure HTTPS connection is used.
-In order to use HTTPS to access Blocks, you need a number of additional things:
-  * A //domain name// of your own.
-  * A //registrar// managing that domain name on your behalf.
-  * A //DNS provider//, making your domain name available on the internet.
-  * A HTTPS //Certificate// (more on that below).
-Furthermore, if you want to access your Blocks server from the internet, you'll also need connection from the internet to your Blocks server. This is often handled in your router or IT infrastructure, for example using a method known as //port forwarding//. Having your Blocks server accessible through the internet makes it easy for visitors to connect to Blocks using their mobile phones.
-===Obtaining a Certificate===
-You must obtain a HTTPS certificate from an accredited //Certificate Authority// (CA). Furthermore, since certificates expire after some time, you must renew your certificate on a regular basis. Fortunately, there's a relatively painless method available to do all of this from [[https://letsencrypt.org|Let's Eencrypt]]. The server image comes with Let's Encrypt preinstalled, so once you've got your domain name registered with a DNS (you can check this using the //nslookup// terminal command), all you need to do is:
-  - Edit the nginx configuration file to specify your domain name, and restart nginx.
-  - Run Let's Encrypt's //certbot// command in the terminal, following its instructions.
-To edit the nginx configuration file, do as follows:
-  * Start the virtual Blocks image.
-  * Log in as the root user (either in the virtualizers terminal window or over ssh and then switch to the root user using **su**).
-  * Open the editor using the command **nano /etc/nginx/sites-available/blocks.conf**
-The //nano// command opens a text editor, showing the configuration, that begins like this:
-<code>
-include /etc/nginx/snippets/pixi-expires.conf;
-server {
-    server_name _;
-</code>
-Replace the underscore character after //server_name// with your domain name, so it looks something like this but with your own domain name instead of //mydomain.com//):
-<code>
-include /etc/nginx/snippets/pixi-expires.conf;
-server {
-    server_name mydomain.com;
-</code>
-Make sure to keep the space  after //server_name// as well as the semicolon after the domain name. Save the result by pressing ctrl-O followed by the Enter key, then exit the //nano// editor by ctrl-X.
-In the same way, edit the file at **/etc/nginx/conf.d/pixilab.conf** by uncommenting (removing the #-signs) the last section under "Redirect ALL http request to https", so it looks like this:
-<code>
-# This file is included inside the main server directive, in the main nginx.con$
-# Allow large uploads (e.g., huge video files) through the proxy
-client_max_body_size 0;
-# Add our own mime type for our JSON-like serialization files
-types {
-    application/x.pixi      pixi;
-}
-# Redirect ALL http request to https
-server {
-    listen 80 default_server;
-    server_name _;
-    return 301 https://$host$request_uri;
-}
-</code>
-Save and exit //nano// again.
-Make sure you've set good, strong passwords on all your Blocks users. Finally, while still as the //root// user, run the following commands, pressing enter after each. The first of these commands checks your new nginx configuration for errors. Pay close attention to any error messages that may appear.
-<code>
-/sbin/nginx -t
-systemctl restart nginx
-certbot --nginx
-</code>
-If the test is successful, then run the second command which  restarts //nginx// to pick up the changed configuration. Finally, the last command tells certbot to do its thing – obtaining a certificate for your domain, integrating it with nginx, etc. If all goes well, you should then be able to access your server from the internet using a URL like this (again using your own domain name):
-<code>
-https://mydomain.com/edit
-</code>
-Certbot will renew your certificate automatically before it expires. You can test automatic renewal for your certificates by running this command:
-<code>
-certbot renew --dry-run
-</code>
-If you get stuck, and need more details, follow the official //certbot// guide found [[https://certbot.eff.org/instructions?ws=nginx&os=debianbuster|here]], keeping in mind that all installations have already been done, so you can skip the first couple of steps.
-===Using Local Wifi===
-While you may use a local wifi network instead of making your Blocks server internet accessible, this adds more complexity for visitors in connecting to your system, since they must first connect to your local wifi and then to your blocks server. Both of these actions can be done from most modern smartphones using QR codes – but you will need two of those, and they need to be scanned in the right order. You of course also need to provide a wifi network with adequate performance and coverage. Thus, for most visitor-facing Blocks applications, internet access is the recommended method.
-If you do opt for a local wifi network, your method for setting up HTTPS also becomes a bit more complicated:
-  - You must provide internet access to your visitors through your local wifi. This is required both to expedite the wifi connection (many phones will refuse to connect to a wifi that doesn't have internet access) and to access the DNS.
-  - Your DNS entry must point to the IP address of your intranet Blocks server, now (hopefully) accessible through your wifi. That means that any attempts to access it from the internet will fail (since it's only available while on the in-house wifi). An "official" DNS entry is required since many smartphones and browsers use some form of "secure DNS", such as [[https://en.wikipedia.org/wiki/DNS_over_HTTPS|DNS over HTTPS]], and will ignore any in-house DNS.
-  - You can't use the automatic "certbot" method mentioned above to obtain a certificate. You must instead use a more complicated DNS-based method.
-=====Security Considerations=====
-This section describes some security considerations. You don't need to do any of this to get a functioning Blocks system.
-===Secure Shell Remote Access (SSH)===
-Secure Shell is not enabled in the VM image. SSH may be useful for many system configuration and remote access purposes. If desired, enable SSH in the VM's console window using the command //systemctl enable ssh// while running as the root user. Before enabling SSH, set a strong password for the blocks user account. The root account is not enabled for SSH access. This can be changed in the file /etc/ssh/sshd_config (not recommended).
-===Firewall===
-The firewall is not enabled in the VM image. Very few services are enabled, so you may not need a firewall since only the required ports are exposed. Feel free to [[https://www.digitalocean.com/community/tutorials/how-to-set-up-a-firewall-with-ufw-on-ubuntu-20-04|configure and enable]] the pre-installed //ufw// firewall if desired. Or, even better, use an external firewall in your IT infrastructure.