git.iko.soy/urbit.org
on 7fa97bd help sign in
urbit.org/docs/using/install.umd
394 lines 11 kB history raw
1:- :~ navhome/'/docs/'
2 navuptwo/'true'
3 next/'true'
4 sort/'1'
5 title/'Install'
6 ==
7;>
9# Install
11Installing Urbit is easy. It just takes a few minutes to get an
12instance up and running on the network.
14Urbit is designed to run on any Unix box with an internet connection.
15macOS, Ubuntu/Debian, FreeBSD, and Fedora all work well.
17If you run into trouble installing Urbit, please let us know via
18email, [questions@urbit.org](mailto:questions@urbit.org), or on the
19forum: [fora.urbit.org](https://fora.urbit.org). You can also chat
20with us at [urbit.org/stream](https://urbit.org/stream).
22> Urbit is alpha software. It’s not yet completely stable, its crypto
23> hasn’t been audited, and there are plenty of rough edges. Urbit is
24> lots of fun to play with, but not quite ready for your important or
25> sensitive data.
27## Build from source
29### Dependencies
31Urbit depends on:
33```
34autoconf
35automake
36C compiler (gcc or clang)
37cmake
38curses
39git
40gmp
41libcurl
42libsigsegv
43libtool
44libuv
45meson
46ninja
47openssl
48pkg-config
49python2
50ragel
51re2c
52```
54### Instructions
56First, you'll install the required dependencies to build Urbit from source. Then, you'll clone the Urbit source code, hosted on Github. Next, you'll bootstrap the Git submodules needed for the build. Lastly, you'll run a [Meson](https://github.com/mesonbuild/meson) build on the Urbit source to create your Urbit binary for your host operating system. Then, finally, you'll be able to boot your urbit.
58For your host OS platform and relevant package installer, run the respective Bash shell commands listed below in a fresh terminal window to get Urbit installed:
60> For those new to the command line, see:
61> - Mac: [Introduction to the Mac OS X Command Line](http://blog.teamtreehouse.com/introduction-to-the-mac-os-x-command-line)
62> - Linux: [An Introduction to the Linux Terminal](https://www.digitalocean.com/community/tutorials/an-introduction-to-the-linux-terminal)
64#### macOS
66##### Homebrew
68> [Homebrew installation guide](https://treehouse.github.io/installation-guides/mac/homebrew)
70```
71# Bash
73brew update
74brew install autoconf automake cmake gcc git gmp libsigsegv libtool meson ninja pkg-config python2 openssl re2c
75git clone https://github.com/urbit/urbit
76cd urbit
77./scripts/bootstrap
78./scripts/build
79sudo ninja -C ./build/ meson-install
80urbit
81```
84##### Macports
86```
87# Bash
89sudo port selfupdate
90sudo port install autoconf automake cmake gmp libsigsegv meson openssl
91git clone https://github.com/urbit/urbit
92cd urbit
93./scripts/bootstrap
94./scripts/build
95sudo ninja -C ./build/ meson-install
96urbit
97```
99#### Linux
101##### Linuxbrew
103> [Linuxbrew](http://linuxbrew.sh/)
105```
106# Bash
108brew update
109brew install autoconf automake cmake gcc git gmp libsigsegv libtool meson ninja pkg-config python2 openssl re2c
110git clone https://github.com/urbit/urbit
111cd urbit
112./scripts/bootstrap
113./scripts/build
114sudo env "PATH=$PATH" ninja -C ./build/ install
115urbit
116```
118N.B. if the step `./scripts/build` fails when attempting to
119build libh2o, it could be caused by a bug in version 0.46 of meson (the bug
120is not present in 0.45 and is fixed in 0.47).
122If the command `meson -v` returns a version starting with 0.46, try these steps:
125```
126brew uninstall meson
127pip install meson=0.47.0
128rm -rf build
129build/scripts
130```
132If that is successful, resume the above instructions after the `build` step.
134##### Ubuntu or Debian
136```
137# Bash
139sudo apt-get update
140sudo apt-get install autoconf automake cmake exuberant-ctags g++ git libcurl4-gnutls-dev libgmp3-dev libncurses5-dev libsigsegv-dev libssl-dev libtool make openssl pkg-config python python3 python3-pip ragel re2c zlib1g-dev
141sudo -H pip3 install --upgrade pip
142sudo -H pip3 install meson==0.29
144# we need ninja 1.5.1
145# 'apt-get install ninja-build' gives us 0.1.3
146# 'apt-get install ninja-build' gives us 1.3.4
148git clone git://github.com/ninja-build/ninja.git
149pushd ninja
150git checkout release
151./configure.py --bootstrap
152sudo cp ./ninja /usr/local/bin
153popd
155git clone https://github.com/urbit/urbit
156cd urbit
157./scripts/bootstrap
158./scripts/build
159sudo ninja -C ./build/ install
160urbit
161```
163```
164(tested on Google Cloud Platform
165 * Ubuntu Trusty Linux (14.04 LTS)
166 * Ubuntu Xenial Linux (16.04 LTS)
167 * Debian 8 (Jessie)
168 * Debian 9 (Stretch)
169on 6 July 2018)
170```
172##### Fedora / Redhat
174```
175# Bash
177sudo yum upgrade
178sudo yum install autoconf automake cmake ctags gcc gcc-c++ git gmp-devel libcurl-devel libsigsegv-devel libtool ncurses-devel ninja-build openssl openssl-devel pkgconfig python2 python3 ragel re2c wget
180# meson requires python 3.5; RHEL supplies wrong version
181pushd /usr/src
182sudo wget https://www.python.org/ftp/python/3.5.5/Python-3.5.5.tgz
183sudo tar xzf Python-3.5.5.tgz
184cd Python-3.5.5
185sudo ./configure --enable--optimizations
186sudo make altinstall
187which python3.5
188cd /usr/local/bin
189sudo ln -s python3.5 python3
190hash python3
191popd
193curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
194sudo /usr/local/bin/python3 get-pip.py
195# downgrade meson to avoid dependencies that redhat can't meet
196sudo -H /usr/local/bin/pip3 install meson==0.29
198git clone git://github.com/ninja-build/ninja.git && cd ninja
199git checkout release
200./configure.py --boostrap
201sudo cp ./ninja /usr/local/bin
203git clone https://github.com/urbit/urbit
204cd urbit
205./scripts/bootstrap
206./scripts/build
207sudo /usr/local/bin/ninja -C ./build/ install
208urbit
209```
211```
212(tested on Google Cloud Platform
213 * Red Hat Enterprise Linux 6.1
214 * Red Hat Enterprise Linux 7.1
215on 5 July 2018)
216```
218##### FreeBSD
220```
221# Bash or Sh
223pkg upgrade
224sudo pkg install autoconf automake cmake curl gcc git gmake gmp libsigsegv libtool python python3 ragel re2c ncurses openssl gmp
225curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
226sudo python3 get-pip.py
227sudo -H pip install --upgrade pip
228sudo -H pip install meson
229sudo pkg install ninja
230git clone https://github.com/urbit/urbit
231cd urbit
232sh ./scripts/bootstrap
233sh ./scripts/build
234sudo ninja -C ./build/ meson-install
235urbit
236```
238```
239(tested on Google Cloud Platform
240 * FreeBSD 10.4
241 * FreeBSD 11.2
242on 4 July 2018)
243```
245##### Arch
247```
248# Bash
250sudo pacman -Syu
251sudo pacman -S autoconf automake cmake curl gcc git gmp libsigsegv libtool ncurses ninja openssl python ragel re2c
252curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
253sudo python3 get-pip.py
254git clone https://github.com/urbit/urbit
255cd urbit
256./scripts/bootstrap
257./scripts/build
258sudo ninja -C ./build/ meson-install
259urbit
260```
262```
263(tested on Amazon EC2 using Amazon Machine Image
264 * Release 2018.06.15 / ebs hvm x86_64 lts ( ami-a40a47db via https://www.uplinklabs.net/projects/arch-linux-on-ec2/ )
265on 6 July 2018)
266```
268##### AWS
270```
271# Bash
273sudo yum update
274sudo yum install autoconf automake cmake ctags gcc gcc-c++ git gmp-devel libcurl-devel libsigsegv-devel libtool ncurses-devel openssl openssl-devel pkgconfig python2 python3 python3-pip ragel re2c wget git
275sudo env "PATH=$PATH" pip3 install --upgrade pip
276sudo env "PATH=$PATH" pip3 install meson
278# we need libsigsegv
281wget http://dl.fedoraproject.org/pub/fedora/linux/releases/25/Everything/x86_64/os/Packages/l/libsigsegv-2.10-10.fc24.x86_64.rpm
282wget http://dl.fedoraproject.org/pub/fedora/linux/releases/25/Everything/x86_64/os/Packages/l/libsigsegv-devel-2.10-10.fc24.x86_64.rpm
283sudo yum localinstall libsigsegv-2.10-10.fc24.x86_64.rpm
284sudo yum localinstall libsigsegv-devel-2.10-10.fc24.x86_64.rpm
286# we need re2c
288wget https://rpmfind.net/linux/dag/redhat/el6/en/x86_64/dag/RPMS/re2c-0.13.5-1.el6.rf.x86_64.rpm
289sudo yum localinstall re2c-0.13.5-1.el6.rf.x86_64.rpm
291git clone git://github.com/ninja-build/ninja.git
292pushd ninja
293git checkout release
294./configure.py --bootstrap
295sudo cp ./ninja /usr/local/bin
296popd
298git clone https://github.com/urbit/urbit
299cd urbit
300./scripts/bootstrap
301./scripts/build
302sudo env "PATH=$PATH" ninja -C ./build/ install
304urbit
305```
307```
308(tested on Amazon EC2 using Amazon Machine Image
309 * Amazon Linux 2 AMI (HVM), SSD Volume Type - ami-b70554c8
310on 6 July 2018)
311```
313### Test for successful installation
315After running your installed `urbit` command, check to see if the following output was printed:
317```
318$ urbit
319Urbit: a personal server operating function
320https://urbit.org
321Version 0.5.1
323Usage: urbit [options...] ship_name
324where ship_name is a @p phonetic representation of an urbit address
325without the leading '~', and options is some subset of the following:
327-A dir Use dir for initial galaxy sync
328-b Batch create
329-B pill Bootstrap from this pill
330-c pier Create a new urbit in pier/
331-d Daemon mode
332-D Recompute from events
333-F Fake keys; also disables networking
334-f Fuzz testing
335-g Set GC flag
336-H domain Set ames bootstrap domain (default urbit.org)
337-I galaxy Start as ~galaxy
338-k stage Start at Hoon kernel version stage
339-l port Initial peer port
340-M Memory madness
341-n host Set unix hostname
342-N Enable networking in fake mode (-F)
343-p ames_port Set the HTTP port to bind to
344-P Profiling
345-q Quiet
346-r host Initial peer address
347-R Report urbit build info
348-s Pill URL from arvo git hash
349-t ticket Use ~ticket automatically
350-u url URL from which to download pill
351-v Verbose
352-w name Immediately upgrade to ~name
353-x Exit immediately
354-Xwtf Skip last event
356Development Usage:
357 To create a development ship, use a fakezod:
358 urbit -FI zod -A /path/to/arvo/folder -B /path/to/pill -c zod
360 For more information about developing on urbit, see:
361 https://github.com/urbit/urbit/blob/master/CONTRIBUTING.md
363Simple Usage:
364 urbit -c <mycomet> to create a comet (anonymous urbit)
365 urbit -w <myplanet> -t <myticket> if you have a ticket
366 urbit <myplanet or mycomet> to restart an existing urbit
367```
369If so, then you're ready to boot your urbit. If not, check that you entered each Bash command correctly for your host OS platform. If you're still experiencing issues, feel free to drop into [Urbit chat](https://urbit.org/stream) for troubleshooting help.
371### Boot your urbit
373You've now installed the Urbit binary. If you're running Urbit on a normal modern PC or Mac, or
374on a large cloud instance, move onto the next [setup](../setup/) section.
376If you're running Urbit in the cloud on a small instance, read
377the below section, as you may need to additionally configure swap space, then continue.
379### (Set up swap)
381Urbit wants to map 2GB of memory when it boots up. We won’t necessarily
382use all this memory, we just want to see it. On a normal modern PC or Mac,
383or on a large cloud virtual machine, this is not an issue. On some small
384cloud virtual machines (Amazon or Digital Ocean), the default memory
385configuration is smaller than this, and you need to manually configure a
386swapfile.
388Digital Ocean has a post on adding swap
389[here](https://www.digitalocean.com/community/tutorials/how-to-add-swap-space-on-ubuntu-16-04).
390For Amazon there’s a StackOverflow thread
391[here](http://stackoverflow.com/questions/17173972/how-do-you-add-swap-to-an-ec2-instance).
393Don’t spend a lot of time tweaking these settings; the simplest
394thing is fine.