git.iko.soy/urbit.org
on c19bc7a help sign in
urbit.org/docs/using/install.udon
399 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.
57Then, you'll clone the Urbit source code, hosted on Github. Next, you'll
58bootstrap the Git submodules needed for the build. Lastly, you'll run a
59[Meson](https://github.com/mesonbuild/meson) build on the Urbit source to create
60your Urbit binary for your host operating system. Then, finally, you'll be able
61to boot your urbit.
63For 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:
65> For those new to the command line, see:
66 - Mac: [Introduction to the Mac OS X Command Line](http://blog.teamtreehouse.com/introduction-to-the-mac-os-x-command-line)
67 - Linux: [An Introduction to the Linux Terminal](https://www.digitalocean.com/community/tutorials/an-introduction-to-the-linux-terminal)
69#### macOS
71##### Homebrew
73> [Homebrew installation guide](https://treehouse.github.io/installation-guides/mac/homebrew)
75```
76# Bash
78brew update
79brew install autoconf automake cmake gcc git gmp libsigsegv libtool meson ninja pkg-config python2 openssl re2c
80git clone https://github.com/urbit/urbit
81cd urbit
82./scripts/bootstrap
83./scripts/build
84sudo ninja -C ./build/ meson-install
85urbit
86```
89##### Macports
91```
92# Bash
94sudo port selfupdate
95sudo port install autoconf automake cmake gmp libsigsegv meson openssl
96git clone https://github.com/urbit/urbit
97cd urbit
98./scripts/bootstrap
99./scripts/build
100sudo ninja -C ./build/ meson-install
101urbit
102```
104#### Linux
106##### Linuxbrew
108> [Linuxbrew](http://linuxbrew.sh/)
110```
111# Bash
113brew update
114brew install autoconf automake cmake gcc git gmp libsigsegv libtool meson ninja pkg-config python2 openssl re2c
115git clone https://github.com/urbit/urbit
116cd urbit
117./scripts/bootstrap
118./scripts/build
119sudo env "PATH=$PATH" ninja -C ./build/ install
120urbit
121```
123N.B. if the step `./scripts/build` fails when attempting to
124build libh2o, it could be caused by a bug in version 0.46 of meson (the bug
125is not present in 0.45 and is fixed in 0.47).
127If the command `meson -v` returns a version starting with 0.46, try these steps:
130```
131brew uninstall meson
132pip install meson=0.47.0
133rm -rf build
134build/scripts
135```
137If that is successful, resume the above instructions after the `build` step.
139##### Ubuntu or Debian
141```
142# Bash
144sudo apt-get update
145sudo 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
146sudo -H pip3 install --upgrade pip
147sudo -H pip3 install meson==0.29
149# we need ninja 1.5.1
150# 'apt-get install ninja-build' gives us 0.1.3
151# 'apt-get install ninja-build' gives us 1.3.4
153git clone git://github.com/ninja-build/ninja.git
154pushd ninja
155git checkout release
156./configure.py --bootstrap
157sudo cp ./ninja /usr/local/bin
158popd
160git clone https://github.com/urbit/urbit
161cd urbit
162./scripts/bootstrap
163./scripts/build
164sudo ninja -C ./build/ install
165urbit
166```
168```
169(tested on Google Cloud Platform
170 * Ubuntu Trusty Linux (14.04 LTS)
171 * Ubuntu Xenial Linux (16.04 LTS)
172 * Debian 8 (Jessie)
173 * Debian 9 (Stretch)
174on 6 July 2018)
175```
177##### Fedora / Redhat
179```
180# Bash
182sudo yum upgrade
183sudo 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
185# meson requires python 3.5; RHEL supplies wrong version
186pushd /usr/src
187sudo wget https://www.python.org/ftp/python/3.5.5/Python-3.5.5.tgz
188sudo tar xzf Python-3.5.5.tgz
189cd Python-3.5.5
190sudo ./configure --enable--optimizations
191sudo make altinstall
192which python3.5
193cd /usr/local/bin
194sudo ln -s python3.5 python3
195hash python3
196popd
198curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
199sudo /usr/local/bin/python3 get-pip.py
200# downgrade meson to avoid dependencies that redhat can't meet
201sudo -H /usr/local/bin/pip3 install meson==0.29
203git clone git://github.com/ninja-build/ninja.git && cd ninja
204git checkout release
205./configure.py --boostrap
206sudo cp ./ninja /usr/local/bin
208git clone https://github.com/urbit/urbit
209cd urbit
210./scripts/bootstrap
211./scripts/build
212sudo /usr/local/bin/ninja -C ./build/ install
213urbit
214```
216```
217(tested on Google Cloud Platform
218 * Red Hat Enterprise Linux 6.1
219 * Red Hat Enterprise Linux 7.1
220on 5 July 2018)
221```
223##### FreeBSD
225```
226# Bash or Sh
228pkg upgrade
229sudo pkg install autoconf automake cmake curl gcc git gmake gmp libsigsegv libtool python python3 ragel re2c ncurses openssl gmp
230curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
231sudo python3 get-pip.py
232sudo -H pip install --upgrade pip
233sudo -H pip install meson
234sudo pkg install ninja
235git clone https://github.com/urbit/urbit
236cd urbit
237sh ./scripts/bootstrap
238sh ./scripts/build
239sudo ninja -C ./build/ meson-install
240urbit
241```
243```
244(tested on Google Cloud Platform
245 * FreeBSD 10.4
246 * FreeBSD 11.2
247on 4 July 2018)
248```
250##### Arch
252```
253# Bash
255sudo pacman -Syu
256sudo pacman -S autoconf automake cmake curl gcc git gmp libsigsegv libtool ncurses ninja openssl python ragel re2c
257curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
258sudo python3 get-pip.py
259git clone https://github.com/urbit/urbit
260cd urbit
261./scripts/bootstrap
262./scripts/build
263sudo ninja -C ./build/ meson-install
264urbit
265```
267```
268(tested on Amazon EC2 using Amazon Machine Image
269 * Release 2018.06.15 / ebs hvm x86_64 lts ( ami-a40a47db via https://www.uplinklabs.net/projects/arch-linux-on-ec2/ )
270on 6 July 2018)
271```
273##### AWS
275```
276# Bash
278sudo yum update
279sudo 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
280sudo env "PATH=$PATH" pip3 install --upgrade pip
281sudo env "PATH=$PATH" pip3 install meson
283# we need libsigsegv
286wget http://dl.fedoraproject.org/pub/fedora/linux/releases/25/Everything/x86_64/os/Packages/l/libsigsegv-2.10-10.fc24.x86_64.rpm
287wget http://dl.fedoraproject.org/pub/fedora/linux/releases/25/Everything/x86_64/os/Packages/l/libsigsegv-devel-2.10-10.fc24.x86_64.rpm
288sudo yum localinstall libsigsegv-2.10-10.fc24.x86_64.rpm
289sudo yum localinstall libsigsegv-devel-2.10-10.fc24.x86_64.rpm
291# we need re2c
293wget https://rpmfind.net/linux/dag/redhat/el6/en/x86_64/dag/RPMS/re2c-0.13.5-1.el6.rf.x86_64.rpm
294sudo yum localinstall re2c-0.13.5-1.el6.rf.x86_64.rpm
296git clone git://github.com/ninja-build/ninja.git
297pushd ninja
298git checkout release
299./configure.py --bootstrap
300sudo cp ./ninja /usr/local/bin
301popd
303git clone https://github.com/urbit/urbit
304cd urbit
305./scripts/bootstrap
306./scripts/build
307sudo env "PATH=$PATH" ninja -C ./build/ install
309urbit
310```
312```
313(tested on Amazon EC2 using Amazon Machine Image
314 * Amazon Linux 2 AMI (HVM), SSD Volume Type - ami-b70554c8
315on 6 July 2018)
316```
318### Test for successful installation
320After running your installed `urbit` command, check to see if the following output was printed:
322```
323$ urbit
324Urbit: a personal server operating function
325https://urbit.org
326Version 0.6.0
328Usage: urbit [options...] ship_name
329where ship_name is a @p phonetic representation of an urbit address
330without the leading '~', and options is some subset of the following:
332-A dir Use dir for initial galaxy sync
333-b Batch create
334-B pill Bootstrap from this pill
335-c pier Create a new urbit in pier/
336-d Daemon mode
337-D Recompute from events
338-F Fake keys; also disables networking
339-f Fuzz testing
340-g Set GC flag
341-H domain Set ames bootstrap domain (default urbit.org)
342-I galaxy Start as ~galaxy
343-k stage Start at Hoon kernel version stage
344-l port Initial peer port
345-M Memory madness
346-n host Set unix hostname
347-N Enable networking in fake mode (-F)
348-p ames_port Set the HTTP port to bind to
349-P Profiling
350-q Quiet
351-r host Initial peer address
352-R Report urbit build info
353-s Pill URL from arvo git hash
354-t ticket Use ~ticket automatically
355-u url URL from which to download pill
356-v Verbose
357-w name Immediately upgrade to ~name
358-x Exit immediately
359-Xwtf Skip last event
361Development Usage:
362 To create a development ship, use a fakezod:
363 urbit -FI zod -A /path/to/arvo/folder -B /path/to/pill -c zod
365 For more information about developing on urbit, see:
366 https://github.com/urbit/urbit/blob/master/CONTRIBUTING.md
368Simple Usage:
369 urbit -c <mycomet> to create a comet (anonymous urbit)
370 urbit -w <myplanet> -t <myticket> if you have a ticket
371 urbit <myplanet or mycomet> to restart an existing urbit
372```
374If 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.
376### Boot your urbit
378You've now installed the Urbit binary. If you're running Urbit on a normal modern PC or Mac, or
379on a large cloud instance, move onto the next [setup](../setup/) section.
381If you're running Urbit in the cloud on a small instance, read
382the below section, as you may need to additionally configure swap space, then continue.
384### (Set up swap)
386Urbit wants to map 2GB of memory when it boots up. We won’t necessarily
387use all this memory, we just want to see it. On a normal modern PC or Mac,
388or on a large cloud virtual machine, this is not an issue. On some small
389cloud virtual machines (Amazon or Digital Ocean), the default memory
390configuration is smaller than this, and you need to manually configure a
391swapfile.
393Digital Ocean has a post on adding swap
394[here](https://www.digitalocean.com/community/tutorials/how-to-add-swap-space-on-ubuntu-16-04).
395For Amazon there’s a StackOverflow thread
396[here](http://stackoverflow.com/questions/17173972/how-do-you-add-swap-to-an-ec2-instance).
398Don’t spend a lot of time tweaking these settings; the simplest
399thing is fine.