Setting Up a Server

2019 status: Current

The server can be installed on any Debian Linux system (for example, on a desktop machine, a server in the cloud, an Intel NUC, or a Raspberry Pi). You can also set up a Linux VM on your machine using Vagrant. See setting up a server with Vagrant.

You can also set up and run the server software on a MacOS computer, in a more limited way (enough to store and retrieve patient data so the Buendia app will work properly on your tablets, but without self-management functions like automatic backup and software update).

See Hardware Requirements for details on obtaining a server device, client devices, or network hardware.

The Buendia Server

A working Buendia server has the following installed:

• A working OpenMRS system
• The CIEL standard concept dictionary
• The Project Buendia additions to the standard dictionary
• The Project Buendia module

Below are instructions for 4 situations you might be in, whether you are doing a field deployment, or just trying it out.

Deployment on an Intel NUC

You can follow either the Quick Start instructions below, or the full instructions for installing Debian on the NUC manually.

Quick Start

1. Download the latest Buendia system installer ISO from http://staging.buendia.org/buendia-install.iso.
2. Write the installer image to bootable media, using e.g. balenaEtcher if you're on MacOS.
3. Boot an Intel NUC or other system from the USB media. Unless the machine is connected to Ethernet with a DHCP server on the network, you will probably be prompted for networking details. This is a network installer, after all.
4. Follow the prompts related to disk partitioning and boot loader. You can hit enter at any prompt to use the defaults. On the NUC, this is intended to result in a functioning system.
5. The installer will take ~5 minutes to run, maybe longer, depending on your network speed, and download 300-400 MB of additional software.
6. You will be prompted to remove the installer media. When the system reboots, it will take about a minute to finish configuring the system. A login prompt may be shown before the first configuration is complete.
7. After a couple minutes, the OpenMRS console will be available at http://localhost:9000/openmrs/. If you've installed to a NUC and have a buendia Wi-Fi network, the server will be available at http://10.18.0.50:9000/openmrs/.
8. You can log into the console as either buendia or root. The password is the same.

Installing Debian on the NUC

• First, download the Debian Stretch ISO image. The NUC has an oddball WiFi card in it, so the free firmware doesn't work. The easiest solution to this is to use the version of Debian Stretch that contains the non-free firmware from this page, and hope that Richard Stallman doesn't notice and get angry at you. Here is the direct download link as of 2019-06-14.
• Now flash the ISO image onto a USB stick. Balena has made an incredibly simple and friendly open-source flashing utility called Etcher, you should use it! It's here. Installation instructions on the Balena site.
• Put the USB stick into the NUC. You'll want a keyboard, mouse, and HDMI-enabled monitor as well; plug them into the NUC and turn the NUC on (you should see a welcome screen). Choose Install and follow the instructions!

once the usb stick is inserted and the NUC is turned on

• Screen: Debian GNU/Linux UEFI Installer Menu:
  • select: Graphical Install
• Screen: Select Language (1 screen)
  • select: english
• Screen: Select Your Location (1 screen)
  • select: United States
• Screen: Configure Keyboard (1 screen)
  • select: American English (or preference)

loading bars

• Screen: Detect Network Hardware (1 screen)
  • select: yes
  • note: you should have the non-free firmware files loaded onto your usb drive.

loading bars

• Screen: Configure the Network (6 screens)
  • sub-screen: "You may see a message stating: your system has multiple network interfaces. Choose the one to use as the primary network interface during Primary network interface"
    • Select the network: wlp2s0: Intel Corporations Device 24fb (wireless)
    • "wireless" is the thing to note here as this is a headless server setup.
  • sub-screen: "Select the wireless network to use during the installation process."
    • Select: (the network you wish to use) use the arrow keys to highlight the network and hit enter to select.
  • sub-screen: "Choose wEP/Open if the network is open to secured with WEP. Choose WPA/WPA2 if the network is protected with WPA/WPA2 PSK (pre-Shared Key). wireless network type for wlp2s0"
    • select: WPA/WPA2 PSK
  • sub-screen: "Enter the passphrase for WPA/WPA2 PSK authentication. This should be the passphrase defined for the wireless network you are trying to use WPA/WPA2 passphrase for wireless device wlp2s0"
    • enter passphrase as defined by description.

loading bars

- sub-screen: "Please enter the hostname for this system." 
  - hostname: NUC2
- sub-screen: "The domain name is the part of your internet address to the right of your host name. It is often something that ends in .com, .net, .edu, or .org. If you are setting up the home network, you can make something up, but make sure you use the same domain name on all your computers." 
  - domain name: LEAVE_BLANK

• Screen: Set up Users and Passwords (3 screens)
  • sub-screen: "You need to set a password for 'root', the system administrative account. A malicious or unqualified user with root access can have disastrous results, so you should take care to choose a root password that is not easy to guess. It should not be a word found in dictionaries, or a word that could be easily associated with you."
    • password: (select password)
    • re-enter password: (same pass)
  • sub-screen: "A user account will be created for you to use instead of the root account for non-administrative activities."
    • Sub-screen username: buendia (this should be suggested for you and you can just hit enter)
  • sub-screen: A good password will contain a mixture of letters, numbers and punctuation and should be changed at regular intervals.
    • password: (select password)
    • re-enter password: (same pass)
• Screen: Configure the Clock (1 screen)
  • sub-screen: If the desired time zone is not listed, then please go back to the step 'choose language' and select a country that uses the desired time zone.
  • select: Eastern
• Screen: Partition Disks (5 screens)
  • sub-screen: "The installer can guide you through partitioning a disk (using different standard schemes) or, if you prefer, you can do it manually..."
    • select: Guided - use entire disk
  • sub-screen: "Note that all data on disk will be erased, but not before you have confirmed that you really want to make the changes."
    • select: SCSI1 (0,0,0) (sda) - 250.1 GB ATA Samsung SSD 860
    • note: the selection is the nuc, the other option will be the flash drive you have inserted.
  • sub-screen: "Selected for partitioning: SCSI1 (0,0,0) (sda) - 250.1 GB ATA Samsung SSD 860 This disk can be partitioned using one of several different schemes."
    • select: Separate /home partition
  • sub-screen: This is an overview of your current configuration partitions and mount points. Select partition to modify it's settings...
    • ensure all specs match the instructions here.
    • select: Finish partitioning and write changes to disk
  • sub-screen: confirm 'if you continue, the changes listed below will be written to the disks...
    • select: yes

loading bars

• Screen: Configure the Package Manager (3 screens)
  • sub-screen: "The goal is to find a mirror of the Debian archive that is close to you on the netword - be aware that nearby countries, or even your own, may not be the best choice."
    • select: United States
  • sub-screen: "Please select a Debian archive mirror."
    • select: ftp.us.debian.org
  • sub-screen: "If you need to use the HTTP proxy to access the outside world, enter the proxy information here. Otherwise, leave this blank."
    • (leave blank)

loading bars

• Screen: Configuration Popularity Contest (1 screen)
  • sub-screen: "The system may anonymously supply the distribution developers with statistics about the most used packages on this system..."
    • select: no

loading bars

• Screen: Software Selection (1 screen)
  • sub-screen: "At this moment, only the core of the system is installed. To tune the system to your needs, you can choose to install one or more of the following predefined collections of software."
    • check boxes:
      • SSH server
      • standard system utilities
    • uncheck all other boxes: Debian desktop environment ... GNOME ... Xfce ... KDE ... Cinnamon ... MATE ... LXDE web server print server
    • tab to continue button and hit enter

loading bars

• Screen: Installation Complete (1 screen)
  • Remove the USB key (which is the installation media) and select: continue

loading bars

reboot of NUC

• Terminal:
  • login: root (type "root" and press Enter)
  • Password: (password)
  • Edit the /etc/network/interfaces file.
    • Type nano /etc/network/interfaces
    • Go to the bottom of the file and add:

auto wlp2s0
iface wlp2s0 inet dhcp
wpa-ssid mywifiname (replace "mywifiname" with the ssid of your wifi)
wpa-psk mywifipassword (replace "mywifipassword" with the password)

 - Type Ctrl-O, Enter (to save) and then Ctrl-X (to exit)

• You will now be out of the Nano editor (you should see root@NUC2:~# at the bootom of the screen)

• Reboot the server by typing the text below. When the NUC wakes up again, it should now be on the wifi. reboot now

• from root:

  • login: root
  • enter passphrase:

• check you are connected to the internet ping 8.8.8.8

  • ctrl c (to exit ping)

• Install sudo

apt update
apt install sudo

• set buendia to sudo user:

usermod -aG sudo buendia

• Enable apt to grab packages via https

sudo apt install apt-transport-https
sudo nano /etc/apt/sources.list

• Use the arrow key to go down the bottom of the file and add:

deb [trusted=yes] https://projectbuendia.github.io/builds/packages stable main java

[control] + [o] [enter] [control] + [x]

• install the server

sudo apt update
sudo apt install -y buendia-site-test buendia-server buendia-dashboard

• get the inet ip address: ip addr show

• On another browser, go to the ip address adding :9000/openmrs to the end of the address.

  • xx.xx.xx.xx:9000/openmrs
  • If you see the OpenMRS dashboard page, things probably worked.

• Login to the OpenMRS dashboard: go to administration, go to manage buendia profiles

• in a new browser window go to the cloud server and download the latest csv. http://demo.buendia.org:9000/openmrs

  • login (twice)
  • go to administration, go to manage buendia profiles
  • download the csv currently in use.

• Go back to the new server window (xx.xx.xx.xx:9000/openmrs) and upload the csv file.

• On the device you wish to connect the new server to.

  • Open the Buendia app and logout,
  • go to settings,
  • click on buendia server and type in the new server ip address you received from the ip addr show command on the NUC.

You should be connected to the new device! Congrats!

Trying it out on a computer (Windows)

See the document Setting up a server: Windows.

Trying it out on a computer (Mac)

See the document Setting up a server: Mac.

Deployment on an Intel Edison (no longer used)

See Setting up an Intel Edison Server

More info on setting up the networking

Using Ubiquiti Nanostation M2

See Setting up an Access Point.