README.md

   1 # Armadillo File Manager
   2
   3 Armadillo is a web-based file manager. It allows you to list, move, rename,
   4 delete, and download files through your browser. It's the ideal solution for a
   5 home media center, allowing you to manage your files from your couch.
   6
   7 ## Installation
   8
   9 Installation requires the [Go runtime](http://golang.org/doc/install) because
  10 there is no binary distribution yet. To install, use the go command:
  11
  12     $ go get https://github.com/rsesek/armadillo
  13
  14 After building, you will have a binary named `armadillo` in your $GOBIN.
  15
  16 ## Configuration
  17
  18 Armadillo can either be configured using command line parameters or via a JSON
  19 configuration file in `~/.armadillo`. The two important directives are
  20 "JailRoot" and "Port":
  21
  22     {
  23       # No operations will be performed outside of this directory. Everything in
  24       # this directory and below will be served by Armadillo.
  25       "JailRoot": "/path/to/root",
  26
  27       # The port on which to run Armadillo.
  28       "Port": 8084
  29     }
  30
  31 You can also specify these values on the command line. See `armadillo -help` for
  32 more details.
  33
  34 ## Security
  35
  36 Armadillo does not fork itself into a daemon process; it runs under the user
  37 who started it. This is because it needs read and write permission to the file
  38 system.
  39
  40 **NOTE: Armadillo provides no form of authorization or authentication. It is
  41 recommended to either only run it on your local network, or to place it behind
  42 a reverse web proxy like [nginx](http://nginx.org) or
  43 [Apache](http://httpd.apache.org) to provide security.** Configuring those
  44 servers is beyond the scope of this document.
  45
  46 ## Running
  47
  48 On Mac OS X, the recommended way to start Armadillo on launch is to use
  49 launchd. Create a file called
  50 `~/Library/LaunchAgents/org.bluestatic.armadillo.plist` with this content:
  51
  52     <?xml version="1.0" encoding="UTF-8"?>
  53     <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
  54     <plist version="1.0">
  55     <dict>
  56             <key>Label</key>
  57             <string>org.bluestatic.armadillo</string>
  58             <key>ProgramArguments</key>
  59             <array>
  60                     <string>/Users/your_name/Projects/armadillo/armadillo</string>
  61                     <string>-config=/path/to/config.json</string>
  62             </array>
  63             <key>KeepAlive</key>
  64             <false/>
  65             <key>RunAtLoad</key>
  66             <true/>
  67     </dict>
  68     </plist>
  69
  70 Then type:
  71
  72     launchctl load ~/Library/LaunchAgents/org.bluestatic.armadillo.plist
  73
  74 And armadillo will start serving with the configuration file you specified in
  75 the plist. The next time you log in, armadillo will run automatically.
  76
  77 ## Contributing
  78
  79 Contributions to armadillo are welcome. There is a Makefile used for local
  80 development builds. There are four targets of interest to contributors:
  81
  82 * `backend`: This target merely runs the go build command in the local directory.
  83 * `frontend`: Generates the frontend "binary" armadillo.js by referencing and
  84   loading all the other frontend files. This is used for debugging and iterative
  85   development.
  86 * `all`: The default target, which executes `backend` and `frontend`.
  87 * `release`: Like `all`, but rather than generating a frontend binary for
  88   debugging, this runs the frontend code through the
  89   [Closure Compiler](https://developers.google.com/closure/compiler/) to minify
  90   and optimize it.
  91
  92 All other targets are reserved for the project maintainer.
  93
  94 Patches can be distributed via pull requests, if your history and commit
  95 messages are clean.  Please also follow existing code style conventions.