Difference between revisions of "Downloading and installing"

From Bisq Wiki
Jump to navigation Jump to search
m
(add details on building from source, as well as downloading and verifying binaries)
Line 1: Line 1:
https://docs.bisq.network/getting-started.html#download-install
+
[[Category:Use Cases]]
 +
 
 +
Unlike most exchanges, Bisq doesn’t run a centralized server for making and taking offers, so trading on a website isn't possible.
 +
 
 +
Instead, Bisq manages offers to trade using a peer-to-peer network—a global network of people who are also running Bisq on their own computers.
 +
 
 +
This is good news for you as a user, because centralized services are easy to monitor, block, and shut down, while peer-to-peer networks like BitTorrent, Bitcoin and Bisq are difficult to surveil, censor, and hack.
 +
 
 +
All of this means that if you want to use the Bisq network, you’ve got to download and run the software too!
 +
 
 +
== Download Bisq ==
 +
 
 +
The most convenient way to install Bisq on your machine is from a pre-built install file from the [https://bisq.network/downloads/ Bisq website] or [https://github.com/bisq-network/bisq/releases/latest latest GitHub release].
 +
 
 +
There's also a community-maintained [https://snapcraft.io/bisq-desktop Snap package] for various Linux distributions.
 +
 
 +
You can download the installer for your operating system and install Bisq right away, but we strongly recommend that you [[ #Verify installer file | verify the integrity ]] of your installer file first.
 +
 
 +
'''If you have issues, please check the ''Known issues with installation'' section in [https://github.com/bisq-network/bisq/releases/latest release notes].'''
 +
 
 +
== Verify installer file ==
 +
 
 +
Any software that manages funds, signs transactions, and deals with highly sensitive data is a prime target for malware. Bisq does all 3. Therefore it's highly recommended that you verify the integrity of the installer file you use to install Bisq.
 +
 
 +
This is just something you should do for the initial Bisq install—afterward, when updates to Bisq are available, you'll be prompted to download and install them through Bisq's interface, and the software will verify the integrity of updates for you.
 +
 
 +
Bisq installer files are currently built and signed by Christoph Atteneder (ripcurlx). His public key ID is <code>29CDFD3B</code> and fingerprint is <code>CB36 D7D2 EBB2 E35D 9B75 500B CD5D C1C5 29CD FD3B</code>, which you can verify through [https://github.com/bisq-network/bisq/commits?author=ripcurlx commits on GitHub] and [https://keybase.io/ripcurlx on Keybase].
 +
 
 +
The full public key is available [https://bisq.network/pubkey/29CDFD3B.asc here on the Bisq website].
 +
 
 +
=== Obtain signature files for installer files ===
 +
 
 +
To verify your installer file is intact and as the developer intended, you'll need the PGP signature file corresponding to the installer file you downloaded.
 +
 
 +
On the Bisq website's download page, download the PGP signature file for the installer file you downloaded before.
 +
 
 +
If you'd prefer to download from GitHub instead, you'll see the <code>.asc</code> file for your installer in the assets section [https://github.com/bisq-network/bisq/releases/latest of the release] along with the installer file itself.
 +
 
 +
In either case, the filename for the <code>.asc</code> you download should be identical to the filename for the installer file, just with <code>.asc</code> appended (e.g., signature file for <code>Bisq-1.2.7.dmg</code> would be <code>Bisq-1.2.7.dmg.asc</code>).
 +
 
 +
=== Windows ===
 +
 
 +
Once you've downloaded the installer file and corresponding signature file:
 +
 
 +
'''Download and install Gpg4win'''
 +
 
 +
Windows doesn't come with GPG software installed by default, so you'll need to install it in order to verify Bisq's installer files.
 +
 
 +
You can get Gpg4win [https://www.gpg4win.org/ here].
 +
 
 +
Double-click the installer file and proceed to install with all default settings.
 +
 
 +
'''Import ripcurlx's public key'''
 +
 
 +
In Kleopatra, import ripcurlx's public key file <code>29CDFD3B.asc</code>. Select ''No'' if asked to mark the certificate as valid.
 +
 
 +
'''Verify the signature of the binary you downloaded'''
 +
 
 +
With the <code>install-file.exe</code> and <code>signature-file.exe.asc</code> in the same directory, double-click on the <code>.exe.asc</code> file.
 +
 
 +
You should see a Kleopatra window pop up with a green progress bar that says "Verified .exe with .exe.asc". The program will continue to say "The data could not be verified" in bold but you can disregard that message.
 +
 
 +
This means the installer file we downloaded is intact and as intended! You can proceed to install Bisq by double-clicking the <code>.exe</code> file.
 +
 
 +
=== macOS and Linux ===
 +
 
 +
Once you've downloaded the installer file and corresponding signature file:
 +
 
 +
'''Import ripcurlx's public key'''
 +
 
 +
Run:
 +
 
 +
<nowiki>curl https://bisq.network/pubkey/29CDFD3B.asc | gpg --import</nowiki>
 +
 
 +
You might see an ominous-sounding warning along the lines of "This key is not certified with a trusted signature". This basically means that none of the public keys on your machine have signed the key you just imported (and that you haven't explicitly indicated you trust this key yourself). This is not necessarily a bad thing, but please see more about what this means [https://serverfault.com/a/569923 here]. In short, you can verify the integrity of this key by [[ #Verify installer file | cross-referencing ripcurlx's Bisq commit signatures and Keybase profile]].
 +
 
 +
'''Verify the signature of the binary you downloaded'''
 +
 
 +
With the installer file and installer signature file in the same directory, run:
 +
 
 +
<nowiki>gpg --digest-algo SHA256 --verify SIGNATURE-FILE.asc </nowiki>
 +
 
 +
Where <code>SIGNATURE-FILE.asc</code> is the filename of the <code>.asc</code> file you just downloaded.
 +
 
 +
You should see output that looks something like:
 +
 
 +
gpg: Signature made Thu 13 Feb 2020 01:38:03 PM EST
 +
gpg:                using RSA key CB36D7D2EBB2E35D9B75500BCD5DC1C529CDFD3B
 +
gpg:                issuer ...
 +
gpg: Good signature from "Christoph Atteneder ..."
 +
 
 +
Great—this means the installer file we downloaded is intact and as intended!
 +
 
 +
'''Verify jar file after installation'''
 +
 
 +
As one last check, you can verify the hash of the jar file after installing Bisq.
 +
 
 +
On macOS, the default location of the jar file is:
 +
 
 +
/Applications/Bisq.app/Contents/Java/
 +
 
 +
On Linux, the default location of the jar file is:
 +
 
 +
/opt/Bisq/app/
 +
 
 +
Get the hash of the jar file with:
  
[[Category:Stubs]]
+
shasum -a256 /path/to/jar/file/jar-name.jar
[[Category:Use Cases]]
+
 
 +
The hash you get should match the hash in the <code>.jar.txt</code> file in the [https://github.com/bisq-network/bisq/releases/latest release assets].
 +
 
 +
== Build from source ==
 +
 
 +
[https://github.com/bisq-network/bisq/blob/master/docs/build.md Building Bisq from source] requires just 1 command once you have the correct JDK installed on your machine.
  
Arch Linux -  
+
Finding and installing the correct JDK can sometimes be frustrating, so Bisq's developers have written scripts to make it easier:
 +
* [https://github.com/bisq-network/bisq/blob/master/scripts/install_java.sh For Linux and macOS]
 +
* [https://github.com/bisq-network/bisq/blob/master/scripts/install_java.bat For Windows]
  
There are two important points, only partly specified so far on bisq downloads site:
+
== OS-specific install notes ==
  
1 (specified already) AUR is the Arch User Repository where the community has package details for Bisq (https://aur.archlinux.org/packages/bisq/)
+
=== Arch Linux ===
  
2 (not specified, but important for unfamiliar Arch users) From the command line, you first clone the repo from AUR, then from the cloned directory use `makepkg -si`. That will read the PKGBUILD file to get, verify, build, and install the various tools necessary to install Bisq.
+
The Bisq [https://bisq.network/downloads/ downloads page] includes a link to the Arch User Repository (AUR) page for the [https://aur.archlinux.org/packages/bisq/ bisq package].
  
3* it should also be stated that when you're using AUR, you're taking your safety in your own hands. Be sure you trust the PKGBUILD file, or you could be footcannoning.  
+
# From the command line, clone the repository from AUR.
 +
# Then from the cloned directory, run <code>makepkg -si</code>. This will read the PKGBUILD file to download, verify, build, and install the various tools necessary to install Bisq.
  
You will then have Bisq!
+
Please be advised: when you're using AUR, you're responsible for your own safety. Be sure to verify the PKGBUILD file.

Revision as of 00:55, 2 March 2020


Unlike most exchanges, Bisq doesn’t run a centralized server for making and taking offers, so trading on a website isn't possible.

Instead, Bisq manages offers to trade using a peer-to-peer network—a global network of people who are also running Bisq on their own computers.

This is good news for you as a user, because centralized services are easy to monitor, block, and shut down, while peer-to-peer networks like BitTorrent, Bitcoin and Bisq are difficult to surveil, censor, and hack.

All of this means that if you want to use the Bisq network, you’ve got to download and run the software too!

Download Bisq

The most convenient way to install Bisq on your machine is from a pre-built install file from the Bisq website or latest GitHub release.

There's also a community-maintained Snap package for various Linux distributions.

You can download the installer for your operating system and install Bisq right away, but we strongly recommend that you verify the integrity of your installer file first.

If you have issues, please check the Known issues with installation section in release notes.

Verify installer file

Any software that manages funds, signs transactions, and deals with highly sensitive data is a prime target for malware. Bisq does all 3. Therefore it's highly recommended that you verify the integrity of the installer file you use to install Bisq.

This is just something you should do for the initial Bisq install—afterward, when updates to Bisq are available, you'll be prompted to download and install them through Bisq's interface, and the software will verify the integrity of updates for you.

Bisq installer files are currently built and signed by Christoph Atteneder (ripcurlx). His public key ID is 29CDFD3B and fingerprint is CB36 D7D2 EBB2 E35D 9B75 500B CD5D C1C5 29CD FD3B, which you can verify through commits on GitHub and on Keybase.

The full public key is available here on the Bisq website.

Obtain signature files for installer files

To verify your installer file is intact and as the developer intended, you'll need the PGP signature file corresponding to the installer file you downloaded.

On the Bisq website's download page, download the PGP signature file for the installer file you downloaded before.

If you'd prefer to download from GitHub instead, you'll see the .asc file for your installer in the assets section of the release along with the installer file itself.

In either case, the filename for the .asc you download should be identical to the filename for the installer file, just with .asc appended (e.g., signature file for Bisq-1.2.7.dmg would be Bisq-1.2.7.dmg.asc).

Windows

Once you've downloaded the installer file and corresponding signature file:

Download and install Gpg4win

Windows doesn't come with GPG software installed by default, so you'll need to install it in order to verify Bisq's installer files.

You can get Gpg4win here.

Double-click the installer file and proceed to install with all default settings.

Import ripcurlx's public key

In Kleopatra, import ripcurlx's public key file 29CDFD3B.asc. Select No if asked to mark the certificate as valid.

Verify the signature of the binary you downloaded

With the install-file.exe and signature-file.exe.asc in the same directory, double-click on the .exe.asc file.

You should see a Kleopatra window pop up with a green progress bar that says "Verified .exe with .exe.asc". The program will continue to say "The data could not be verified" in bold but you can disregard that message.

This means the installer file we downloaded is intact and as intended! You can proceed to install Bisq by double-clicking the .exe file.

macOS and Linux

Once you've downloaded the installer file and corresponding signature file:

Import ripcurlx's public key

Run:

curl https://bisq.network/pubkey/29CDFD3B.asc | gpg --import

You might see an ominous-sounding warning along the lines of "This key is not certified with a trusted signature". This basically means that none of the public keys on your machine have signed the key you just imported (and that you haven't explicitly indicated you trust this key yourself). This is not necessarily a bad thing, but please see more about what this means here. In short, you can verify the integrity of this key by cross-referencing ripcurlx's Bisq commit signatures and Keybase profile.

Verify the signature of the binary you downloaded

With the installer file and installer signature file in the same directory, run:

gpg --digest-algo SHA256 --verify SIGNATURE-FILE.asc 

Where SIGNATURE-FILE.asc is the filename of the .asc file you just downloaded.

You should see output that looks something like:

gpg: Signature made Thu 13 Feb 2020 01:38:03 PM EST
gpg:                using RSA key CB36D7D2EBB2E35D9B75500BCD5DC1C529CDFD3B
gpg:                issuer ...
gpg: Good signature from "Christoph Atteneder ..."

Great—this means the installer file we downloaded is intact and as intended!

Verify jar file after installation

As one last check, you can verify the hash of the jar file after installing Bisq.

On macOS, the default location of the jar file is:

/Applications/Bisq.app/Contents/Java/

On Linux, the default location of the jar file is:

/opt/Bisq/app/

Get the hash of the jar file with:

shasum -a256 /path/to/jar/file/jar-name.jar

The hash you get should match the hash in the .jar.txt file in the release assets.

Build from source

Building Bisq from source requires just 1 command once you have the correct JDK installed on your machine.

Finding and installing the correct JDK can sometimes be frustrating, so Bisq's developers have written scripts to make it easier:

OS-specific install notes

Arch Linux

The Bisq downloads page includes a link to the Arch User Repository (AUR) page for the bisq package.

  1. From the command line, clone the repository from AUR.
  2. Then from the cloned directory, run makepkg -si. This will read the PKGBUILD file to download, verify, build, and install the various tools necessary to install Bisq.

Please be advised: when you're using AUR, you're responsible for your own safety. Be sure to verify the PKGBUILD file.