Installation & Setup

VA Explorer is distributed and installed using Docker. Docker supports near automatic configuration and installation of VA Explorer no matter where you choose to install it. In general, you can expect an installation and hosting of VA Explorer to involve these steps:

1. Obtain a server (either your own hardware or cloud provider)

2. Obtain a web address/domain name

3. Prepare server to host VA Explorer

4. Deploy and run VA Explorer via Docker

5. Create your first Admin account and log in

Depending on how many of these are already in place, feel free to skip to the step most relevant to you.

Obtain a server (either your own hardware or cloud provider)

A Linux Operating System (OS) is recommended for best ease of use and for taking maximal advantage of docker later. One such OS that VA Explorer has been reliably tested on is Ubuntu. To get a server:

• If using a cloud provider, select and provision one of their Ubuntu server instances according to their instructions.

• If provisioning your own server, you may be able to do so through your organization or hosting provider (see Step 2).

While not required, hardware specifications for the server that has successfully hosted VA Explorer in the past had a reference baseline of 1 CPU, 16 GB RAM, and 1 TB Storage.

Obtain a web address/domain name

A domain name such as my-va-explorer.com is required for users to navigate to your server from a browser. If you already own a domain, a subdomain (my-va-explorer.my-website.com) is a good approach too. If you already own a domain name, please proceed to the next step.

For those wishing to acquire a domain name, your organization may be able to provide one or you can pay a commercial domain registrar for one. Please note that new domains can take some time to be accessible from the Internet. While waiting, you need to direct this domain to the hosted server from Step 1:

• If using a cloud provider, please follow their instructions on connecting domain names to their hosted server instances.

• If you’ve provisioned your own server through your organization or hosting provider but they are not able to provide a domain name, that server should have an IP address. You’ll need to follow the instructions of your domain registrar to point the newly registered domain name to your server’s IP address.

Prepare server to host VA Explorer

To bring your server from blank slate to ready-to-host, there are final some steps to take before downloading VA Explorer.

• Install Docker Engine on Ubuntu

• Install Docker Compose Standalone

• Post Installation Setup for Docker Users on Linux

• Install a web server/ reverse proxy to direct web traffic to the VA Explorer port. Two popular options are Nginx and Apache. An example Apache configuration is provided in the Troubleshooting section

• If your hosting provider doesn’t already or automatically provide https support, you should add it now. Let’s Encrypt is a free https certificate provider that also provides a guides for adding https support to Apache or Nginx web servers, among other configurations.

• Tools like git and text editors like vim will also be needed. You can install them via sudo apt install -y git vim or your OS’s equivalent

Deploy and run VA Explorer via Docker

VA Explorer itself is quick to deploy thanks to Docker and the default configurations. More on customizing this configuration can be found in Configuration & Deployment.

• Assuming you’ve ssh’d into the server, navigate to the directory you’d like to install VA Explorer in.

• Retrieve the latest version of VA Explorer via: git clone https://github.com/VA-Explorer/va_explorer.git then navigate into the created directory via cd va_explorer

• You can provide initial configuration to supplement defaults by creating a .env file. Do so via mv .env.template .env and vim .env. One variable that can be edited immediately is the DJANGO_ALLOWED_HOSTS variable by adding your domain name from Step 2. For more information on this, see the mentioned Configuration & Deployment section.

• Run docker-compose up -d --build. If you experience any issues here, please consult the Troubleshooting section.

• Additionally, the full and complete list of management commands is available by running manage.py help. Only some of the popular commands are described here or in Management Commands.

• VA Explorer should now be up and running. You can confirm services are running as expected via docker ps which should output like below:

docker ps output showing the pycrossva, clereryworker, django, flower, interva5, redis, and postgres services running

Create your first Admin account and log in

Finally, to get started in the application you should create an admin account for yourself. This can be done via built-in management command from within the main web application container. To seed an admin user for yourself:

• Open a shell within the main web application docker container by running docker exec -it va_explorer_django_1 bash

• Run the seed_admin_user command via manage.py seed_admin_user <EMAIL_ADDRESS> filling in your own email for the email parameter

• A temporary password will print to the console. Copy it. In a browser,navigate to the domain name you chose in Step 2 and log in with the email you provided plus the password you copied.

• You should now be logged in and immediately prompted to reset your password to something of your choosing. Take the opportunity to do so now.

Once you have one account you do not have to repeat this process as the application provides admins an interface for creating and managing other users.

With this basic setup in place you are ready to get started. As mentioned, if you are interested in reading more about basic or advanced configuration options like allowing an email server to handle user password resets you can find that in the next section Configuration & Deployment. You may also want to read over IT Support Guides for information on activities like setting up an email server, implementing server monitoring, and preparing for regular backups.