bootstrap.html

{% extends "base.html" %} {% block title %}Bootstrapping Instructions{% endblock
%} {% block content %}
<h1>Bootstrapping Instructions</h1>
<h2>1. Setting Up a POSIX Environment</h2>
<h3>A. Installing MSYS2</h3>
<p>
  MSYS2 is a POSIX environment which provides extensive compiler support for the
  more modern programming languages used by Murfey's package dependencies.
</p>
<p>
  The Murfey server supports the forwarding of download requests to
  network-restricted client PCs. To install MSYS2, download the setup executable
  using this
  <a href="{{ proxy_path }}/msys2/repo/distrib/msys2-x86_64-latest.exe"
    >mirror</a
  >, then run it using the default settings. This will install MSYS2 to
  <span
    style="font-family: Consolas, Monaco, &quot;Lucida Console&quot;, monospace"
  >
    C:\msys64 </span
  >.
</p>
<p>
  Some versions of Windows are too old to support the default MSYS2 installer.
  In such cases, download this alternative
  <a href="{{ proxy_path }}/msys2/repo/distrib/msys2-x86_64-latest.sfx.exe"
    >executable</a
  >
  and run it. It will unpack the
  <span
    style="font-family: Consolas, Monaco, &quot;Lucida Console&quot;, monospace"
    >msys64</span
  >
  folder into your Downloads folder. Copy this folder to the default MSYS2
  location, and run the UCRT64 executable within it to proceed with the
  installation as normal.
</p>
<h3>B. Setting Up MSYS2</h3>
<h4>i. Setting Up the MSYS2 Package Manager (If Network-Restricted)</h4>
<p>
  By default, MSYS2 comes with preset lists of mirrors and servers that it
  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
  <a href="{{ proxy_path }}/msys2/config/pacman.d.zip">link</a>.
</p>
<p>
  Once downloaded, extract the files to
  <span
    style="font-family: Consolas, Monaco, &quot;Lucida Console&quot;, monospace"
    >%MSYS64%\etc\pacman.d</span
  >. If MSYS2 was installed at the default location, this will be:
</p>
<pre
  style="font-family: Consolas, Monaco, &quot;Lucida Console&quot;, monospace"
>
  C:\msys64\etc\pacman.d
</pre>
<h4>ii. Installing Dependencies</h4>
<p>
  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:
</p>
<pre
  style="font-family: Consolas, Monaco, &quot;Lucida Console&quot;, monospace"
>
  $ pacman -Syu
  $ pacman -S msys2-runtime
  $ pacman -S rsync
  $ pacman -S mingw-w64-ucrt-x86_64-python-pip
  $ pacman -S mingw-w64-ucrt-x86_64-rust
</pre>
<p>
  Other utility packages such as
  <span
    style="font-family: Consolas, Monaco, &quot;Lucida Console&quot;, monospace"
    >vim</span
  >
  can also be installed by running
  <span
    style="font-family: Consolas, Monaco, &quot;Lucida Console&quot;, monospace"
    >pacman -S &lt;package-name&gt;</span
  >. You can browse the other packages available on MSYS2 by searching the repo
  using
  <span
    style="font-family: Consolas, Monaco, &quot;Lucida Console&quot;, monospace"
    >pacman -Ss &lt;package-name&gt;</span
  >
</p>
<h4>Downgrading Python packages</h4>
<p>
  MSYS2 current installs Python 3.14 by default, which we have not rigorously
  tested Murfey with. For now, we downgrade to Python 3.12.12, which is known to
  work with Murfey. To do so, download the following packages:
</p>
<ul>
  <li>
    <a
      href="{{ proxy_path }}/msys2/repo/mingw/ucrt64/mingw-w64-ucrt-x86_64-python-3.12.12-1-any.pkg.tar.zst"
      style="
        font-family: Consolas, Monaco, &quot;Lucida Console&quot;, monospace;
      "
      >mingw-w64-ucrt-x86_64-python-3.12.12-1-any.pkg.tar.zst</a
    >
  </li>
  <li>
    <a
      href="{{ proxy_path }}/msys2/repo/mingw/ucrt64/mingw-w64-ucrt-x86_64-python-distlib-0.4.0-2-any.pkg.tar.zst"
      style="
        font-family: Consolas, Monaco, &quot;Lucida Console&quot;, monospace;
      "
      >mingw-w64-ucrt-x86_64-python-distlib-0.4.0-2-any.pkg.tar.zst</a
    >
  </li>
  <li>
    <a
      href="{{ proxy_path }}/msys2/repo/mingw/ucrt64/mingw-w64-ucrt-x86_64-python-pip-25.3-2-any.pkg.tar.zst"
      style="
        font-family: Consolas, Monaco, &quot;Lucida Console&quot;, monospace;
      "
      >mingw-w64-ucrt-x86_64-python-pip-25.3-2-any.pkg.tar.zst</a
    >
  </li>
  <li>
    <a
      href="{{ proxy_path }}/msys2/repo/mingw/ucrt64/mingw-w64-ucrt-x86_64-python-setuptools-80.9.0-2-any.pkg.tar.zst"
      style="
        font-family: Consolas, Monaco, &quot;Lucida Console&quot;, monospace;
      "
      >mingw-w64-ucrt-x86_64-python-setuptools-80.9.0-2-any.pkg.tar.zst</a
    >
  </li>
</ul>
<p>
  These files will be placed in your account's Downloads folder by default, and
  can then be installed using the following command:
</p>
<pre
  style="font-family: Consolas, Monaco, &quot;Lucida Console&quot;, monospace"
>
  $ pacman -U /c/Users/&lt;username&gt;/Downloads/&lt;package-name&gt;</pre
>

<h4>iii. Configuring the Rust Package Manager (If Network-Restricted)</h4>
<p>
  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.
</p>
<p>
  Rust packages and their associated metadata are, by default, stored in
  <span
    style="font-family: Consolas, Monaco, &quot;Lucida Console&quot;, monospace"
    >https://crates.io</span
  >. Package download and installation is in turn conducted by the package
  manager
  <span
    style="font-family: Consolas, Monaco, &quot;Lucida Console&quot;, monospace"
    >cargo</span
  >. For network-restricted client PCs, Murfey also supports mirroring
  <span
    style="font-family: Consolas, Monaco, &quot;Lucida Console&quot;, monospace"
    >https://crates.io</span
  >
  to facilitate the installation of Rust packages.
</p>
<p>
  To configure
  <span
    style="font-family: Consolas, Monaco, &quot;Lucida Console&quot;, monospace"
    >cargo</span
  >, simply download the pre-configured
  <span
    style="font-family: Consolas, Monaco, &quot;Lucida Console&quot;, monospace"
    >config.toml</span
  >
  file via this <a href="{{ proxy_path }}/rust/cargo/config.toml">link</a>. This
  file should then be pasted in a
  <span
    style="font-family: Consolas, Monaco, &quot;Lucida Console&quot;, monospace"
    >.cargo</span
  >
  folder, which, by default, should be located in your User Profile homespace:
</p>
<pre
  style="font-family: Consolas, Monaco, &quot;Lucida Console&quot;, monospace"
>
  %USERPROFILE%\.cargo
</pre>
<p>For a user named Murfey, for example, this would take the form:</p>
<pre
  style="font-family: Consolas, Monaco, &quot;Lucida Console&quot;, monospace"
>
  C:\Users\Murfey\.cargo
</pre>
<p>
  With this file configured,
  <span
    style="font-family: Consolas, Monaco, &quot;Lucida Console&quot;, monospace"
    >cargo</span
  >
  will know to look for package metadata and files via the Murfey mirror
  instead.
</p>

<h2>2. Setting Up Python</h2>
<p>
  Once Python and
  <span
    style="font-family: Consolas, Monaco, &quot;Lucida Console&quot;, monospace"
    >pip</span
  >
  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.
</p>
<h3>A. (Optional) Setting Up a Virtual Environment</h3>
<p>To set up a virtual environment, run the following commands:</p>
<pre
  style="font-family: Consolas, Monaco, &quot;Lucida Console&quot;, monospace"
>
  $ 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
</pre>
<h3>B. Installing Murfey</h3>
<p>
  You can install Murfey in the Python environment (the base one or a virtual
  environment) in the UCRT64 terminal using the following commands:
</p>
<pre
  style="font-family: Consolas, Monaco, &quot;Lucida Console&quot;, monospace"
>
  $ pip install murfey --index-url {{ request.url.scheme }}://{{ netloc }}{{ proxy_path }}/pypi/index --trusted-host {{ netloc }}
</pre>

<h4>Installing Pillow</h4>
<p>
  Python's Pillow package will be needed for certain instruments. This will
  require the installation of additional image libraries in
  <span
    style="font-family: Consolas, Monaco, &quot;Lucida Console&quot;, monospace"
    >pacman</span
  >:
</p>
<pre
  style="font-family: Consolas, Monaco, &quot;Lucida Console&quot;, monospace"
>
  $ pacman -S \
    mingw-w64-ucrt-x86_64-freetype \
    mingw-w64-ucrt-x86_64-giflib \
    mingw-w64-ucrt-x86_64-lcms2 \
    mingw-w64-ucrt-x86_64-libjpeg-turbo \
    mingw-w64-ucrt-x86_64-libpng \
    mingw-w64-ucrt-x86_64-libtiff \
    mingw-w64-ucrt-x86_64-libwebp \
    mingw-w64-ucrt-x86_64-openjpeg2 \
    mingw-w64-ucrt-x86_64-zlib
</pre>
<p>
  Once the necessary libraries have been installed, Pillow can be installed by
  running the following command:
</p>
<pre
  style="font-family: Consolas, Monaco, &quot;Lucida Console&quot;, monospace"
>
  $ ZLIB_ROOT="/ucrt64" pip install pillow --index-url {{ request.url.scheme }}://{{ netloc }}{{ proxy_path }}/pypi/index --trusted-host {{ netloc }}
</pre>

{% endblock %}