Follow these steps to set up your own installation of Proxl on your own computer. These instructions include running Proxl with default settings and require only minimal configuration by the user. If you already have access to Proxl (e.g. at https://www.yeastrc.org/proxl_public/), you do not need to do this to use Proxl.
This tutorial assumes you have Docker installed on your system. Please see our Docker Installation Tutorial to get Docker installed.
System Requirements: Proxl will consume a large amount of RAM, particularly when uploading data. You should have at least 6 gigabytes of RAM available on your system.
1. Open a Terminal¶
On Linux and MacOS, open a normal terminal. On Windows, if you followed our instructions for installing Docker, follow the directions on our Docker Installation Tutorial to open a Linux terminal.
2. Install Docker Compose¶
Docker Compose is an official add-on to Docker that greatly simplifies running applications that have multiple parts. Proxl has several parts, including a database, multiple web applications, and running programs. Docker Compose allows you to run a single command to launch and correctly stitch all of those components together into a working system. This all happens inside of Docker and does not install the software elsewhere on your computer.
If you are on MacOS, you will likely already have Docker Compose installed. If you are on Linux (including
Windows users who installed Docker according to our instructions), test if Docker Compose is installed
docker-compose. If the command is not found, please install Docker Compose by typing the following:
sudo curl -L "https://github.com/docker/compose/releases/download/1.29.1/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose sudo chmod +x /usr/local/bin/docker-compose
If you run into any trouble installing Docker Compose, please see Docker’s official Docker Compose installation instructions.
3. Download Proxl Install Files¶
First set up a Proxl project directory:
mkdir ~/proxl cd ~/proxl
Now, download the Proxl Docker Compose files:
# Download Proxl Docker Compose files curl -L "https://github.com/yeastrc/proxl-web-app/releases/latest/download/docker-compose-files.tgz" -o docker-compose-files.tgz # Expand the archive tar -xvzf docker-compose-files.tgz
If you prefer to download a ZIP file or if you prefer to download the file another way, the latest release can be found on GitHub at https://github.com/yeastrc/proxl-web-app/releases/latest
4. Configure Proxl¶
Copy the sample configuration file into place:
cp docker/env-sample ./.env
What follows below in this step is optional. Your installation of proxl will be more secure if you change the default passwords. The instructions below describe how to do this.
.env file holds all of the necessary configuration for Proxl. It is recommended (but not required)
that you change the first two lines of the file, which contain passwords to be used for the MySQL database.
.env file should look something like this:
# .env file for supplying settings to initializing proxl using docker-compose # Change these passwords. MYSQL_ROOT_PASSWORD=change_this_password MYSQL_PASSWORD=change_this_password # Can change the mysql user proxl uses, but not necessary MYSQL_USER=proxl_db_user # name of the proxl database PROXL_DATABASE_NAME=proxl # Used by importer PROXL_WEB_APP_BASE_URL=http://proxl:8080/proxl/ # This manages the memory usage of components of proxl IMPORTER_JAVA_OPTIONS=-Xmx3g -Xms500m WEBAPP_JAVA_OPTIONS=-Xms2024m -Xmx2024m # This manages optimization settings for MySQL MYSQL_OPTIONS=--max-connections=500 --skip-ssl # Settings for setting up sending of emails by proxl SMTP_HOST=smtp.example.com SMTP_PORT=587 SMTP_USERNAME=smtp_username SMTP_PASSWORD=smtp_password
These can be changed using your favorite text editor. On Linux (including Docker on Windows), we’ll assume
nano. To edit the file, type:
Change the passwords and type
Control-x to save and exit.
By default, Docker manages where data are stored on your disk. If you would like to customize where proxl stores data, please follow our Customize Data Locations tutorial. This should be done before continuing on to Step 6 below. Once that is complete, proceed to Step 6.
5. Starting and Stopping Proxl¶
At this point, starting and stopping Proxl should be straight forward.
To start Proxl:
sudo docker-compose up --detach
To stop Proxl:
sudo docker-compose down
If you are using Windows, ensure Docker is running by typing:
sudo service docker start
You should now be able to start Proxl.
The first time you start Proxl, all of the components will download and the database will initialize. This may take a few minutes, depending on your download speed. Subsequent startups of Proxl will not require these steps and will be faster.
These commands must be typed while you are in the project code directory. If you followed these instructions, you can ensure you are in this directory by typing:
6. Connect to Your Proxl Installation¶
Point your web browser to http://localhost:8080/proxl/ to access Proxl running on your own computer!
If this is the first time bringing up Proxl, it may take a minute for the database to initialize. If you see message saying there was a problem with your request, try again in about a minute.
Login with Default User¶
By default, you can log in using
admin as the username and
changeme as the password.
(Optional) Change Default User Information¶
For security reasons, you should change the default log in information of the admin user. To change the default information click on the Account Settings icon in the top right of the page:
Change the name, username, and password in the form to your liking.
Start Using Proxl¶
That’s it, you are ready to use Proxl!
7. (Optional) Set up SMTP For Emails¶
Some functions of Proxl require sending email to users. Examples of this include inviting new users to projects, resetting forgotten passwords, and notifications that data uploads have been completed. Although it’s not required that you set up SMTP, the above features will not be enabled unless you do. If you would like to enable these features, please see our Proxl SMTP Setup Guide.
If you do not set up SMTP, you must use the administrative interface to add new users to proxl. The manage users icon can be found at the top-right after logging in as an administrative user.