 }})
Bootstrapping instructions
-Installing a Linux Terminal
-Installing Cygwin
+1. Setting Up a POSIX Environment
+Option 1: Installing Cygwin
- If you already have a Cygwin install, rename it so that it doesn't get - overwritten (something like "[install name]-old"). + Cygwin is a lightweight POSIX environment that provides the minimum + requirements needed for a Windows client PC to efficiently transfer files to a + Unix storage server. However, it currently does not support building and + installing packages which have been written in Rust, which many modern Python + packages, including Murfey's dependencies, now make use of. Nevertheless, + older versions of Murfey will still work with it.
- Download the Cygwin setup executable using this - mirror, and then run the following from - a terminal (both Command Prompt and Windows Powershell work) + To install, download the Cygwin setup executable using this + mirror, and then run + the following from a terminal (both Command Prompt and Windows Powershell + work):
-
- $ setup-x86_64.exe -O -R C:\cygwin64 -s {{ request.url.scheme }}://{{ request.url.netloc }}/cygwin -P curl,python3,rsync -q
+
+ $ setup-x86_64.exe -O -R C:\cygwin64 -s {{ request.url.scheme }}://{{ netloc }}{{ proxy_path }}/cygwin -P curl,python3,rsync -q
- The Cygwin install sometimes hangs even when it is finished, hit Enter to
- return to a command prompt.
+ This will install Cygwin with the minimum packages needed to run Murfey. The
+ Cygwin install command will occasionally hang after completion. In such an
+ event, just hit Enter to return to a normal command prompt window.
+
+
+ If you already have a Cygwin install that you would like to preserve, rename
+ it so that it doesn't get overwritten (something like "cygwin64-old") before
+ running the command line above.
-Installing MSYS2
+Option 2: Installing MSYS2
- MSYS2 is a lightweight Linux environment which provides compiler support for
- the more modern programming languages used in the backend of Murfey's package
- dependencies.
+ MSYS2 is a lightweight POSIX environment which provides compiler support for
+ the more modern programming languages used by Murfey's package dependencies.
- The Murfey server supports the forwarding of download requests to client PCs
- that cannot access the wider internet. Download the MSYS2 setup executable
- using this mirror, and run the
- executable using the default settings.
+ The Murfey server supports the forwarding of download requests to
+ network-restricted client PCs. To install MSYS2, download the setup executable
+ using this
+ mirror, then run it using the default settings. This will install MSYS2 to
+ C:\msys64.
+A. Setting Up the Package Manager (If Network-Restricted)
By default, MSYS2 comes with preset lists of mirrors and servers that it
- installs its packages from. These will need to be disabled, and replaced with
- URLs of the same format that point to the Murfey server the client PC is
- connected to.
+ installs its packages from. On a network-restricted PC, these will need to be
+ replaced with files that point to the Murfey server instead. They can be
+ downloaded via this
+ link.
- These lists can be found in the following folder, if the default installation
- options were chosen:
+ Once downloaded, extract the files to
+ %MSYS64%\etc\pacman.d. If MSYS2 was installed at the default location, this will be:
-
- C:\msys64\etc\pacman.d\mirrorlist.{environment}
-
-This is an example of how the URL to the Murfey server should look like:
-
- Server = https://repo.msys2.org/mingw/x86_64/ # Original URL
- Server = {{ request.url.scheme }}://{{ request.url.netloc }}/msys2/mingw/x86_64 # Murfey URL
+
+ C:\msys64\etc\pacman.d
+B. Installing Dependencies
MSYS2 comes with multiple environments, but UCRT64 is the most modern one. In
order for the Murfey client to be able to install and run its dependencies
properly, the following packages will need to be installed in the UCRT64
environment. This can be achieved using the following commands:
-
- $ pacman -Syu --disable-download-timeout # Downloads the package database and searches for updates
- $ pacman -S rsync --disable-download-timeout
- $ pacman -S mingw-w64-python-pip --disable-download-timeout
- $ pacman -S mingw-w64-x86_64-rust --disable-download-timeout
+
+ $ pacman -Syu
+ $ pacman -S msys2-runtime-3.6
+ $ pacman -S rsync
+ $ pacman -S mingw-w64-ucrt-x86_64-python-pip
+ $ pacman -S mingw-w64-ucrt-x86_64-rust
+
+
+ Other utility packages such as
+ vim
+ can also be installed by running
+ pacman -S <package-name>. You can browse the other packages available on MSYS2 by searching the repo
+ using
+ pacman -Ss <package-name>
+
+C. Configuring the Rust Package Manager (If Network-Restricted)
+
+ Many newer Python packages now have dependencies written in Rust that allow
+ them to operate more efficiently. MSYS2 supports the compilation and
+ installation of such packages, and is thus our recommended POSIX environment
+ to use Murfey with.
+
+
+ Rust packages and their associated metadata are, by default, stored in
+ https://crates.io. Package download and installation is in turn conducted by the package
+ manager
+ cargo. For network-restricted client PCs, Murfey also supports mirroring
+ https://crates.io
+ to facilitate the installation of Rust packages.
+
+
+ To configure
+ cargo, simply download the pre-configured
+ config.toml
+ file via this link. This
+ file should then be pasted in a
+ .cargo
+ folder, which, by default, shold be located in your User Profile homespace:
+
+
+ %USERPROFILE%\.cargo
+
+For a user named Murfey, for example, this would take the form:
+
+ C:\Users\Murfey\.cargo
+
+ With this file configured,
+ cargo
+ will know to look for package metadata and files via the Murfey mirror
+ instead.
+
+
+D. Running MSYS2 Through Command Prompt
+
+ In order to run Murfey via the terminal, MSYS2 will have to be run through
+ Windoww's Command Prompt terminal, as there is an ongoing bug with MSYS2's
+ pre-packaged terminal that prevents mouse interaction with interactive apps in
+ the terminal.
+
+
+ To do so, simply right-click on your desktop and navigate to
+ New > Shortcut. When prompted for the location of the item, enter
+ the following into the text box:
+
+
+ cmd.exe /k "C:\msys64\msys2_shell.cmd -defterm -no-start -ucrt64 -shell bash"
+
+
+ After naming the shortcut, click Finish to create the shortcut. This will run
+ a UCRT64 instance of MSYS2 through the Command Prompt terminal that starts you
+ off in MSYS2's default home directory. You can proceed to customise the
+ shortcut icon to taste.
+
-Setting Up Python
+2. Setting Up Python
Once Python and pip are installed in the terminal, you have the option to
install Murfey in either the base environment or a virtual environment. The
base environment is simpler, but uninstallation of the Python packages in the
future could potentially interfere with the base environment's functionality.
-Setting Up a Virtual Environment
+A. (Optional) Setting Up a Virtual Environment
To set up a virtual environment, run the following commands:
-
- $ pip install virtualenv --index-url {{ request.url.scheme }}://{{ request.url.netloc }}/pypi --trusted-host {{ request.url.hostname }}
+
+ $ pip install virtualenv --index-url {{ request.url.scheme }}://{{ netloc }}{{ proxy_path }}/pypi --trusted-host {{ netloc }}
$ virtualenv your-env-name # Create the virtual environment
$ source your-env-name/bin/activate # Activate the virtual environment
-Installing Murfey
+B. Installing Murfey
You can install Murfey in the Python environment (the base one or a virtual
environment) in either the Cygwin or UCRT64 terminal using the following
commands:
-
- $ pip install murfey[client] --index-url {{ request.url.scheme }}://{{ request.url.netloc }}/pypi --trusted-host {{ request.url.hostname }}
+
+ $ pip install murfey[client] --index-url {{ request.url.scheme }}://{{ netloc }}{{ proxy_path }}/pypi --trusted-host {{ netloc }}
+
+ If you wish to install the client-side dependencies needed to run Murfey via
+ the web UI, replace
+ murfey[client]
+ with
+ murfey[client,instrument-server].
+
{% endblock %}