BUILD.md 8.48 KB
Newer Older
1
# Building and Running Snowdrift
2

3
Snowdrift has been built successfully on many GNU/Linux distros and on macOS.
4

5 6
Windows and \*BSD distributions are not currently supported, but we will assist
any efforts to add such support. See below for partial setup instructions.
7

8 9
## Install System Dependencies

Aaron Wolf's avatar
Aaron Wolf committed
10
[Git], [PostgreSQL], [Stack], and [Make] are the only dependencies needed at the
11 12
system level. Stack takes care of finding or installing the correct GHC version.
Some systems need a few additional libraries to support the core dependencies.
13

14
**Follow the details for your system, then skip to the "Get the Snowdrift Code"
15 16
section.**

17
### Debian, Ubuntu, and any related derivatives
18

19
Install Git, PostgreSQL and Make with needed libraries:
20

21
    sudo apt-get update
22
    sudo apt-get install git postgresql libgmp-dev libpq-dev libssl-dev make
23

Bryan Richter's avatar
Bryan Richter committed
24
Then follow the [Debian Stack install] or [Ubuntu Stack install] instructions
25
as appropriate.
26

27
### CentOS/RHEL and Fedora
28

29
* Install Git, needed libraries and Make:
30

31
        sudo dnf install git gcc-c++ gmp-devel ncurses-devel openssl-devel zlib-devel make
32

Iko's avatar
Iko committed
33
    For CentOS and Fedora <=22, replace the `dnf` commands with `yum`. Fedora <=23
34
may also need the `libstdc++-static` package.
35

36
* You'll also need PostgreSQL >= 9.3:
37

Iko's avatar
Iko committed
38
        sudo dnf install postgresql-server postgresql-devel
39

40 41 42 43 44 45 46 47
    If the version in the distro repositories is too old, follow the
    [instructions on the PostgreSQL wiki] to install from their repositories.
    Get the postgresqlXX-server and postgresqlXX-devel packages, where XX is the
    version number. In this case, the pgsql executables will be installed in
    `/usr/pgsql-X.X/bin`. For the Snowdrift database cluster tool to see the
    executables, either add that route (with the correct numbers instead of X.X)
    to your PATH (e.g. in `~/.bash_profile`, `~/.bashrc` or `~/.profile`) or
    create symlinks somewhere already on your PATH.
48

49
* Follow the [Stack install instructions] for your distribution.
50

51
### Arch Linux
52

53
Install Git, PostgreSQL, Stack and Make by running this command as `root`:
54

55
    pacman -S git postgresql stack make
56

57 58 59 60
Arch also requires installation of the ncurses5-compat-libs package, found in
the AUR.  If you are unsure how to install from the AUR, please refer to the
[AUR ArchWiki Page].

61
Once ncurses5-compat-libs is installed, add the following line to
62 63 64 65 66 67
~/.stack/config.yaml:

~~~~~
ghc-build: nopie
~~~~~

Aaron Wolf's avatar
Aaron Wolf committed
68 69 70 71 72
**NOTE: Entering this into ~/.stack/config.yaml will apply to *all* Haskell
projects that you build using stack going forward.** This command tells stack
to use a version of ghc that compiles without PIE. We were unable to find a way
to set this configuration *just* for Snowdrift, however we don't believe making
this change will cause any issues with compiling other Haskell projects.
73

74 75 76 77 78 79 80 81 82 83 84
### NixOS

Use `nix-shell` to provide Stack and the Yesod executable:

    nix-shell -p stack haskellPackages.yesod-bin

Add the following to `~/.stack/config.yaml`:

    nix:
      enable: true

85
### \*BSD
86

87 88 89 90
*Status:* We welcome testing but do not officially support \*BSD distributions
due to Stack being unavailable for some \*BSD platforms. The site has run
successfully on FreeBSD with non-trivial changes to the build process
(due to hlibsass linking of C libraries). For more details, please refer to this
Iko's avatar
Iko committed
91
[discussion about FreeBSD].
92

93
### OS X
94

95
If you don't have [brew] yet, install it with:
Aaron Wolf's avatar
Aaron Wolf committed
96 97 98

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

99
With brew, install the core dependencies:
100 101 102 103

    brew install git
    brew install postgres
    brew install haskell-stack
104
    brew install make
105

106
### Windows
107

108
**Status:** We welcome testing but do not officially support Windows.
109

110 111 112 113
In the past, we have had only partial success running on Windows. We know that
our development database scripts won't work on Windows because they use UNIX
sockets. We welcome any patches, feedback, or Postgres-on-Windows help to get an
alternative working.
114

115
## Get the Snowdrift code
116

Aaron Wolf's avatar
Aaron Wolf committed
117 118 119
Our primary repository is at [git.snowdrift.coop/sd/snowdrift], and our
instructions assume that repository. For convenience and redundancy, we also
mirror at [GitHub].
120

121
From within your preferred directory, get the code with:
122

123
    git clone https://git.snowdrift.coop/sd/snowdrift.git
124

125
Change to the new snowdrift directory:
126 127

    cd snowdrift
128

129
## Run the tests
130

131
Run the tests to fetch and build all Haskell dependencies:
132

133
    ./build.sh test
134

135 136
This will take a while!

137
## Running the site
138

139
Run the site in development mode with
140

141
    ./build.sh
142

143 144
This will automatically rebuild and rerun the site whenever it detects
changes to the code.
145 146

To stop the site, type `quit` in the terminal, then press Enter.
147

148 149
## Troubleshooting

150
If `./build.sh` commands fail in any way, try running `./build.sh cleandb` and
151
then building again.
152

153 154 155 156 157 158
## Using the local site

### View in your browser

Access the site in your browser at <http://localhost:3000>

159 160
### Using auth in development

161 162 163 164
You can log in to the locally-running site using the default user
`user@example.com` and passphrase `userpassphrase`.

To create a new account, follow these instructions:
165

166 167 168 169 170 171
As the development site does not normally send out emails (the authentication
approach for the live Snowdrift.coop system), you can get the necessary auth
tokens from the debug output in the terminal.

After sending an auth form request in the web interface, look for the following
line
172 173 174

    (AuthToken {fromAuthToken = "TOKEN"})

175 176 177 178 179 180 181 182
but where `TOKEN` is instead a random alpha-numerical string that you can input
when prompted to verify the request (and don't get confused by other shorter
random strings that also show up nearby in the terminal).

Although it's not recommended, you can also enable sending mail (if you have an
appropriate mail server accessible) by setting the environment variable
`SD_EMAILS` to "true", or by modifying `website/config/settings.yml` with the
setting `send-email: "_env:SD_EMAILS:true"`. Just be careful who you try to send
183
mail to.
184

185 186
### Using Stripe in development

Bryan Richter's avatar
Bryan Richter committed
187 188
1. Register an account on the [Stripe] website.

189 190
2. At your Stripe dashboard, make sure "View test data" is turned **on**
   (which is default for new accounts but worth double-checking).
Bryan Richter's avatar
Bryan Richter committed
191

192
3. Click the "API" link to obtain your publishable and secret test keys.
193

194 195 196
4. In the top-level directory of the snowdrift project (where we have build.sh),
   create a new text file named `.stripe_keys` and add your keys as environment
   variables:
Bryan's avatar
Bryan committed
197
>>>
198 199
export STRIPE_PUBLISHABLE_KEY=your_stripe_pub_key  
export STRIPE_SECRET_KEY=your_stripe_sec_key
Bryan's avatar
Bryan committed
200
>>>
201

202 203 204 205
5. Build your snowdrift development site and log in.

6. Make sure Javascript is enabled and that no plugins block Stripe's JavaScript
   form.
206

207
7. Navigate to the dashboard payment settings page. Press the "Set up Stripe"
208
   button and provide the following details on the Checkout form:
209 210 211 212
   * One of the [Stripe test card numbers], e.g. "4242 4242 4242 4242"
   * Any future expiration date
   * Any 3-digit CVC code
   * Any postal code, e.g. "12345"
213

214
8. Click "Register" to submit the form and complete the setup.
215

216 217 218 219
#### Updating static files

To make builds recognize changes to the static directory, run:

220
    touch website/src/Settings/StaticFiles.hs
221 222 223

## Getting help, learning, contributing etc.

Bryan Richter's avatar
Bryan Richter committed
224 225 226
We welcome any and all feedback on these build instructions, on the site
itself, etc. We will happily help you with any questions. See the [README] for
further general links, and the [Contributing Guide] for more thorough resources
227
about technical development.
228

229
[AUR ArchWiki Page]: https://wiki.archlinux.org/index.php/Arch_User_Repository
230 231 232
[brew]: http://brew.sh/
[Contributing Guide]: CONTRIBUTING.md
[Debian Stack install]: https://github.com/commercialhaskell/stack/blob/master/doc/install_and_upgrade.md#debian
Iko's avatar
Iko committed
233
[discussion about FreeBSD]: https://git.snowdrift.coop/sd/snowdrift/issues/67
234
[Git]: http://www.git-scm.com/downloads
235
[git.snowdrift.coop/sd/snowdrift]: https://git.snowdrift.coop/sd/snowdrift
236
[GitHub]: https://github.com/snowdriftcoop/snowdrift
237
[instructions on the PostgreSQL wiki]: https://wiki.postgresql.org/wiki/YUM_Installation
238
[Make]: https://www.gnu.org/software/make/manual/html_node/index.html
239
[PostgreSQL]: http://www.postgresql.org/download/
240
[README]: README.md
Aaron Wolf's avatar
Aaron Wolf committed
241
[Stack]: https://github.com/commercialhaskell/stack#the-haskell-tool-stack
242
[Stack install instructions]: https://github.com/commercialhaskell/stack/blob/master/doc/install_and_upgrade.md
243 244
[Stripe]: https://stripe.com
[Stripe test card numbers]: https://stripe.com/docs/testing#cards
245
[Ubuntu Stack install]: https://github.com/commercialhaskell/stack/blob/master/doc/install_and_upgrade.md#ubuntu