Difference between revisions of "Downloading and installing"

From Bisq Wiki
Jump to navigation Jump to search
m (→‎macOS and Linux: ominous sounding is not hyphanated: https://www.grammarbook.com/punctuation/hyphens.asp#:~:text=Generally%2C%20hyphenate%20two%20or%20more,is%20called%20a%20compound%20adjective.&text=When%20a%20compound%20adjective%20follows,The%20apartment%20is%20off%20campus. Parenthetical was awkward. Reworded. Extreneous italics removed.)
 
(20 intermediate revisions by 6 users not shown)
Line 1: Line 1:
To use Bisq, you must first '''[https://bisq.network/downloads/ download and install]''' it. Most exchanges are centralized exchanges running on servers controlled by the exchange. Bisq is decentralized, running only on the desktops of Bisq users.  This means there is no single point of control or failure.  
+
To use Bisq, you must first '''[https://bisq.network/downloads/ download and install]''' it. Most exchanges are centralized exchanges running on servers controlled by the exchange. Bisq is decentralized, running only on the desktops of Bisq users.
  
Bisq manages offers to trade using a peer-to-peer network. This is a global network only made of users who are also running Bisq on their own computers.
+
Bisq manages offers to trade using a peer-to-peer network. This is a global network made of users who are also running Bisq on their own computers.
  
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, shutdown or hack.
+
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, shut down or hack.
  
All of this means that if you want to use the Bisq network, you must download and run the software and become part of the Bisq network.
+
All of this means that if you want to use the Bisq network, you must download and run the software on your own machine.
  
 
== Download Bisq ==
 
== Download Bisq ==
Line 23: Line 23:
 
Any software that manages funds, signs transactions, and deals with highly sensitive data is a prime target for malware. Bisq does all three. Therefore, it is highly recommended that you verify the integrity of the installer file you use to install Bisq.
 
Any software that manages funds, signs transactions, and deals with highly sensitive data is a prime target for malware. Bisq does all three. Therefore, it is highly recommended that you verify the integrity of the installer file you use to install Bisq.
  
This verification is something that you should do for the initial Bisq install. After inital verification and install when updates to Bisq are available, you will be prompted to download and install them through Bisq's interface. The Bisq software will verify the integrity of updates for you.
+
This verification is something that you should do for the initial Bisq install. After the initial install, you will be prompted to install updates through Bisq's interface. The Bisq 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].
+
Bisq installer files are currently built and signed by Alejandro Garcia (alejandrogarcia83). His public key ID is <code>E222AA02</code> and fingerprint is <code>B493 3191 06CC 3D1F 252E  19CB F806 F422 E222 AA02</code>, which you can verify through [https://github.com/bisq-network/bisq/commits?author=alejandrogarcia83 commits on GitHub].
  
The full public key is available [https://bisq.network/pubkey/29CDFD3B.asc here on the Bisq website].
+
The full public key is available [https://bisq.network/pubkey/E222AA02.asc here on the Bisq website].
  
 
=== Obtain signature files for installer files ===
 
=== Obtain signature files for installer files ===
Line 45: Line 45:
 
Once you have downloaded the installer file and corresponding signature file:
 
Once you have downloaded the installer file and corresponding signature file:
  
'''Download ripcurlx's public key'''
+
'''Download alejandrogarcia83 public key'''
  
Download ripcurlx's public key [https://bisq.network/pubkey/29CDFD3B.asc here on the Bisq website].
+
Download alejandrogarcia83 public key [https://bisq.network/pubkey/E222AA02.asc here on the Bisq website].
  
 
'''Download and install Gpg4win'''
 
'''Download and install Gpg4win'''
Line 57: Line 57:
 
Double-click the installer file and proceed to install with all default settings.
 
Double-click the installer file and proceed to install with all default settings.
  
'''Import ripcurlx's public key'''
+
'''Import alejandrogarcia83'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.
+
In Kleopatra, import alejandrogarcia's public key file <code>E222AA02.asc</code>. Select ''No'' if asked to mark the certificate as valid.
  
 
'''Verify the signature of the binary you downloaded'''
 
'''Verify the signature of the binary you downloaded'''
Line 73: Line 73:
 
Once you've downloaded the installer file and corresponding signature file:
 
Once you've downloaded the installer file and corresponding signature file:
  
'''Import ripcurlx's public key'''
+
'''Import alejandrogarcia83's public key'''
  
 
Run:
 
Run:
  
  <nowiki>curl https://bisq.network/pubkey/29CDFD3B.asc | gpg --import</nowiki>
+
  <nowiki>curl https://bisq.network/pubkey/E222AA02.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. It also means that you have not 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]].
+
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. It also means that you have not 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 ajejandrogarcia83's Bisq commit signatures]].
  
 
'''Verify the signature of the binary you downloaded'''
 
'''Verify the signature of the binary you downloaded'''
Line 117: Line 117:
 
  gpg: assuming signed data in 'Bisq-1.6.4.dmg'
 
  gpg: assuming signed data in 'Bisq-1.6.4.dmg'
 
  gpg: Signature made Thu May  6 13:32:43 2021 EDT
 
  gpg: Signature made Thu May  6 13:32:43 2021 EDT
  gpg:                using RSA key CB36D7D2EBB2E35D9B75500BCD5DC1C529CDFD3B
+
  gpg:                using RSA key B493319106CC3D1F252E19CBF806F422E222AA02
  gpg:                issuer "christoph.atteneder@gmail.com"
+
  gpg:                issuer "alejandro.garcia@disroot.org"
 
  gpg: Can't check signature: No public key</nowiki>
 
  gpg: Can't check signature: No public key</nowiki>
  
In this case you haven't imported the public key successfully. Please follow the guide above on how to import the public key for verification.
+
In this case, you have not imported the public key successfully. Please follow the guide above on how to import the public key for verification.
  
 
'''Successful verification'''
 
'''Successful verification'''
Line 128: Line 128:
  
 
  gpg: Signature made Thu 13 Feb 2020 01:38:03 PM EST
 
  gpg: Signature made Thu 13 Feb 2020 01:38:03 PM EST
  gpg:                using RSA key CB36D7D2EBB2E35D9B75500BCD5DC1C529CDFD3B
+
  gpg:                using RSA key B493319106CC3D1F252E19CBF806F422E222AA02
 
  gpg:                issuer ...
 
  gpg:                issuer ...
  gpg: Good signature from "Christoph Atteneder ..."
+
  gpg: Good signature from "Alejandro García <alejandro.garcia@disroot.org>"
  
Great—this means the installer file we downloaded is intact and as intended!
+
Great, this means the installer file we downloaded is intact and as intended.
  
 
'''Verify jar file after installation'''
 
'''Verify jar file after installation'''
Line 144: Line 144:
 
On Linux, the default location of the jar file is:
 
On Linux, the default location of the jar file is:
  
/opt/bisq/bin/Bisq
+
/opt/bisq/bin/Bisq
 +
 
 +
or also
 +
 
 +
/opt/bisq/lib/app/
 +
 
 +
If you cannot find the jar file in the locations above in Linux, you can try finding it by running
 +
 
 +
find / -name "desktop*.jar"
  
 
Get the hash of the jar file with:
 
Get the hash of the jar file with:
Line 154: Line 162:
 
== Build from source ==
 
== 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.  
+
[https://github.com/bisq-network/bisq/blob/master/docs/build.md Building Bisq from source] requires only a single 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:
 
Finding and installing the correct JDK can sometimes be frustrating, so Bisq's developers have written scripts to make it easier:
Line 161: Line 169:
  
 
== OS-specific install notes ==
 
== OS-specific install notes ==
 +
 +
=== macOS ===
 +
 +
Starting with version v1.9.6, we remove notarization from our build pipeline because of of the risk of Apple certification revocation (see https://github.com/bisq-network/bisq/discussions/6341). Unfortunately this will require extra steps when installing Bisq on macOS.
 +
 +
You will receive an error popup saying that Bisq ''is damaged and can't be opened. You should move it to the Trash''.
 +
 +
Please follow the guide at https://support.apple.com/en-us/HT202491 in the section ''If you want to open an app that hasn’t been notarized or is from an unidentified developer''
 +
 +
If you are running already macOS Ventura (13.0+) you need to do following to be able to start Bisq:
 +
* enter following command in Apple Terminal <code>sudo xattr -rd com.apple.quarantine /Applications/Bisq.app</code>
 +
* hit enter and you will be prompted to enter your password to be able to execute the command as super user
 +
 +
After running this successfully you should be able to start Bisq as always.
 +
 +
If this procedure still does not allow you to install Bisq, a last resort workaround is to install Bisq in a Linux Virtual Machine running on your system.
 +
 +
=== Windows ===
 +
 +
Starting with version v1.9.6, we remove the developer code signing because of the same reason as with Apple.
 +
 +
For Windows you just have to ignore the warning after you have verified the installation file yourself and proceed with the installation.
  
 
=== Linux (General) ===
 
=== Linux (General) ===
Line 166: Line 196:
 
Bisq works with a number of Linux distros, but not all desktop environments are supported.  
 
Bisq works with a number of Linux distros, but not all desktop environments are supported.  
  
These are all known working desktop environments (it's a growing list—if you find another one that works, please add it!):
+
These are all known compatible desktop environments. This is a growing list. If you find another compatible desktop, please inform us so it can be added.
  
 
* GNOME
 
* GNOME
Line 184: Line 214:
 
# From the command line, clone the repository from AUR.  
 
# 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.
 
# 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.
 +
 +
If the version found on AUR is not up to date, you can read [[Fix_Arch_release]].
  
 
Please be advised: when you're using AUR, you're responsible for your own safety. Be sure to verify the PKGBUILD file.
 
Please be advised: when you're using AUR, you're responsible for your own safety. Be sure to verify the PKGBUILD file.
 +
 +
=== Gentoo ===
 +
 +
Use <code>eselect repository enable booboo</code> to use the 'booboo' overlay which carries the binaries, and then emerge <code>bisq</code>
  
 
=== Tails ===
 
=== Tails ===
Line 194: Line 230:
  
 
Please see [[Running Bisq on Qubes]] for a detailed Qubes setup guide.
 
Please see [[Running Bisq on Qubes]] for a detailed Qubes setup guide.
 +
 +
== Update Bisq ==
 +
 +
Installing a new Bisq version will update Bisq. More details at [[Updating Bisq]].
  
  
 
[[Category:Use Cases]]
 
[[Category:Use Cases]]

Latest revision as of 20:32, 26 August 2023

To use Bisq, you must first download and install it. Most exchanges are centralized exchanges running on servers controlled by the exchange. Bisq is decentralized, running only on the desktops of Bisq users.

Bisq manages offers to trade using a peer-to-peer network. This is a global network made of users who are also running Bisq on their own computers.

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, shut down or hack.

All of this means that if you want to use the Bisq network, you must download and run the software on your own machine.

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.

Note
See install notes for various Linux distributions below.

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 three. Therefore, it is highly recommended that you verify the integrity of the installer file you use to install Bisq.

This verification is something that you should do for the initial Bisq install. After the initial install, you will be prompted to install updates through Bisq's interface. The Bisq software will verify the integrity of updates for you.

Bisq installer files are currently built and signed by Alejandro Garcia (alejandrogarcia83). His public key ID is E222AA02 and fingerprint is B493 3191 06CC 3D1F 252E 19CB F806 F422 E222 AA02, which you can verify through commits on GitHub.

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 will 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 prefer to download from GitHub, you will 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).

Once you've got the installer file and its corresponding signature file, proceed to the directions for your operating system below.

Windows

Once you have downloaded the installer file and corresponding signature file:

Download alejandrogarcia83 public key

Download alejandrogarcia83 public key here on the Bisq website.

Download and install Gpg4win

Windows does not come with GPG software installed by default, so you will 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 alejandrogarcia83's public key

In Kleopatra, import alejandrogarcia's public key file E222AA02.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 alejandrogarcia83's public key

Run:

curl https://bisq.network/pubkey/E222AA02.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. It also means that you have not 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 ajejandrogarcia83's Bisq commit signatures.

Verify the signature of the binary you downloaded

If you are not familiar with GPG (a free open source version of PGP) you probably need to install GPG command line tools first. Following instructions are taken from https://blog.ghostinthemachines.com/2015/03/01/how-to-use-gpg-command-line.

The easiest way to install the GPG command line tools on your Mac is to first install Homebrew, a package management system that makes thousands of software packages available for install on your Mac.

Open a Terminal window (Applications > Utilities menu), then enter the following command.

ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" 

When that’s complete, install the GPG software package with the following command.

brew install gnupg 

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.

Common errors

gpg: directory '/Users/bisq/.gnupg' created
gpg: keybox '/Users/bisq/.gnupg/pubring.kbx' created
gpg: can't open 'SIGNATURE-FILE.asc': No such file or directory
gpg: verify signatures failed: No such file or directory

In this case, you haven't replaced SIGNATURE-FILE.asc with the actual signature file you want to use e.g. Bisq-1.6.4.dmg.asc

gpg: can't open 'Bisq-1.6.4.dmg.asc': No such file or directory

In this case, you either haven't downloaded the signature file already or you are not in the correct directory. You can run pwd to see the path you are in. If you want to switch to the directory, where the downloaded files are you can use the `cd` command and switch to the correct directory by typing e.g. cd ~/Downloads(switching to the download directory on macOS). To list all files in the current directory you can enter ls -la in your console.

gpg: assuming signed data in 'Bisq-1.6.4.dmg'
gpg: Signature made Thu May  6 13:32:43 2021 EDT
gpg:                using RSA key B493319106CC3D1F252E19CBF806F422E222AA02
gpg:                issuer "alejandro.garcia@disroot.org"
gpg: Can't check signature: No public key</nowiki>

In this case, you have not imported the public key successfully. Please follow the guide above on how to import the public key for verification.

Successful verification

You should see output that looks something like:

gpg: Signature made Thu 13 Feb 2020 01:38:03 PM EST
gpg:                using RSA key B493319106CC3D1F252E19CBF806F422E222AA02
gpg:                issuer ...
gpg: Good signature from "Alejandro García <alejandro.garcia@disroot.org>"

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/bin/Bisq

or also

/opt/bisq/lib/app/

If you cannot find the jar file in the locations above in Linux, you can try finding it by running

find / -name "desktop*.jar"

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 only a single 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

macOS

Starting with version v1.9.6, we remove notarization from our build pipeline because of of the risk of Apple certification revocation (see https://github.com/bisq-network/bisq/discussions/6341). Unfortunately this will require extra steps when installing Bisq on macOS.

You will receive an error popup saying that Bisq is damaged and can't be opened. You should move it to the Trash.

Please follow the guide at https://support.apple.com/en-us/HT202491 in the section If you want to open an app that hasn’t been notarized or is from an unidentified developer

If you are running already macOS Ventura (13.0+) you need to do following to be able to start Bisq:

  • enter following command in Apple Terminal sudo xattr -rd com.apple.quarantine /Applications/Bisq.app
  • hit enter and you will be prompted to enter your password to be able to execute the command as super user

After running this successfully you should be able to start Bisq as always.

If this procedure still does not allow you to install Bisq, a last resort workaround is to install Bisq in a Linux Virtual Machine running on your system.

Windows

Starting with version v1.9.6, we remove the developer code signing because of the same reason as with Apple.

For Windows you just have to ignore the warning after you have verified the installation file yourself and proceed with the installation.

Linux (General)

Bisq works with a number of Linux distros, but not all desktop environments are supported.

These are all known compatible desktop environments. This is a growing list. If you find another compatible desktop, please inform us so it can be added.

  • GNOME
  • Mate
  • Xfce
  • KDE Plasma
  • Cinnamon

Bisq might not work properly if you switch from the original desktop environment of your Linux distribution to a different one.

Note: users with discrete GPUs may encounter issues launching Bisq in some desktop environments.

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.

If the version found on AUR is not up to date, you can read Fix_Arch_release.

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

Gentoo

Use eselect repository enable booboo to use the 'booboo' overlay which carries the binaries, and then emerge bisq

Tails

Please see Running Bisq on Tails for details on downloading, installing, and configuring Bisq on Tails.

Qubes

Please see Running Bisq on Qubes for a detailed Qubes setup guide.

Update Bisq

Installing a new Bisq version will update Bisq. More details at Updating Bisq.