1
- sharry
2
- ======
1
+ # Sharry
3
2
4
3
Sharry allows to share files with others in a simple way. It is a
5
4
self-hosted web application. The basic concept is: upload files and get
6
5
a url back that can then be shared.
7
6
8
- <a href =" https://travis-ci.org/eikek/sharry " ><img src =" https://travis-ci.org/eikek/sharry.svg " ></a >
9
7
<a href =" https://xkcd.com/949/ " ><img height =" 400 " align =" right " style =" float :right " src =" https://imgs.xkcd.com/comics/file_transfer.png " ></a >
10
8
11
- How it works
12
- ------------
9
+ ## How it works
13
10
14
- ### Authenticated users - & gt ; others
11
+ ### Authenticated users → others
15
12
16
13
Authenticated users can upload their files on a web site together with
17
14
an optional password and a time period. The time period defines how long
@@ -20,7 +17,7 @@ can be shared, e.g. via email.
20
17
21
18
The download page is hard to guess, but open to everyone.
22
19
23
- ### Others - & gt ; Authenticated users
20
+ ### Others → Authenticated users
24
21
25
22
Anonymous can send files to registered ones. Each registered user can
26
23
maintain alias pages. An alias page is behind a “hard-to-guess” URL
@@ -29,207 +26,12 @@ corresponding user. The form does not allow to specify a password or
29
26
validation period, but a description can be given. The user belonging to
30
27
the alias can be notified via email.
31
28
32
- ### Others - & gt ; Others
29
+ ## Documentation
33
30
34
- If authentication is enabled, it is not possible to share files between
35
- non-registered users. One party must be registered. But authentication
36
- can be completely disabled. Then any user can upload files. This may be
37
- useful within a closed network.
31
+ Please see the [ documentation site] ( https://eikek.github.io/sharry ) .
38
32
39
- Upload and Download
40
- -------------------
41
33
42
- Sharry aims to provide a good support for large files. That means
43
- downloads and uploads are resumable. Large files can be downloaded via
44
- [ byte serving] ( https://en.wikipedia.org/wiki/Byte_serving ) , which allows
45
- for example to watch video files directly in the browser. Uploads are
46
- resumable, too, by using
47
- [ resumable.js] ( https://github.com/23/resumable.js ) on the client.
48
- Uploads can be retried where only chunks not already at the server are
49
- transferred.
34
+ ## License
50
35
51
- Each published upload has a validity period, after which the public
52
- download page doesn't work anymore. A cleanup job running periodically
53
- can delete those files to save space.
54
-
55
- Features
56
- --------
57
-
58
- - resumable and recoverable upload of multiple files; thanks to
59
- [ resumable.js] ( https://github.com/23/resumable.js )
60
- - validation period for uploads
61
- - resumable downloads using [ byte
62
- serving] ( https://en.wikipedia.org/wiki/Byte_serving )
63
- - download single files or all in a zip
64
- - protect downloads with a password
65
- - automatic removal of invalid uploads
66
- - external authentication (via system command or http requests)
67
- - managing accounts, uploads and alias pages
68
- - a command line client for uploading files
69
-
70
- Try it
71
- ------
72
-
73
- ~~ There is a demo installation at < https://sharrydemo.eknet.org > . You can
74
- use the account ` sharry ` and no password to log in. The mail feature is
75
- not enabled and uploads are restricted to 1.5M.~~ Sorry, I had to shut down this service.
76
-
77
- Or, clone this project and use sbt (see below for prerequisites) to
78
- compile and run:
79
-
80
- ``` shell
81
- sbt run-sharry
82
- ```
83
-
84
- This will build the project and start the server. Point your browser to
85
- < http://localhost:9090 > and login with user ` admin ` and password
86
- ` admin ` .
87
-
88
- Or, download a binary from the [ release
89
- page] ( https://github.com/eikek/sharry/releases ) .
90
-
91
- Documentation
92
- -------------
93
-
94
- These pages are shown in each sharry instance, for example
95
- [ here] ( https://sharrydemo.eknet.org/#manual/index.md ) . The documentation
96
- to the command line client is included.
97
-
98
- Building
99
- --------
100
-
101
- For the server, you need Java8, [ sbt] ( http://scala-sbt.org ) and
102
- [ Elm] ( http://elm-lang.org/ ) installed first. Then clone the project and
103
- run:
104
-
105
- ``` shell
106
- sbt make
107
- ```
108
-
109
- This creates a file in ` modules/server/target/scala-2.12 ` named
110
- ` sharry-server-*.jar.sh ` . This is an executable jar file and can be used
111
- to run sharry:
112
-
113
- The ` --console ` argument allows to terminate the server from the
114
- terminal (otherwise it's ` Ctrl-C ` ). By default a
115
- [ H2] ( http://h2database.com ) database is configured in the current
116
- working directory.
117
-
118
- ``` shell
119
- $ ./modules/server/target/scala-2.12/sharry-server-0.0.1-SNAPSHOT.jar.sh --console
120
- 2017-05-08T14:53:07.345+0200 INFO [main] sharry.server.main$ [main.scala:36]
121
- ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
122
- Sharry 0.0.1-SNAPSHOT (build 2017-05-08 12:49:58UTC) is starting up …
123
- ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
124
- 2017-05-08T14:53:08.563+0200 INFO [main] sharry.server.main$ [main.scala:42]
125
- ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
126
- • Running initialize tasks …
127
- ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
128
- 2017-05-08T14:53:08.622+0200 INFO [main] com.zaxxer.hikari.HikariDataSource [HikariDataSource.java:93] HikariPool-1 - Started.
129
- 2017-05-08T14:53:09.272+0200 INFO [main] sharry.server.main$ [main.scala:62]
130
- ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
131
- • Starting http server at 0.0.0.0:9090
132
- ––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––––
133
- Hit RETURN to stop the server
134
- ```
135
-
136
- The command also builds the command line client. It can be found at
137
- ` modules/cli/target/scala-2.12 ` named ` sharry-cli-*-.jar.sh ` .
138
-
139
- Building only the command line client doesn't require Elm and can be
140
- built separately with ` sbt make-cli ` .
141
-
142
- Dependencies
143
- ------------
144
-
145
- The server and cli part is written in [ Scala] ( http://scala-lang.or ) and
146
- uses the following great libraries:
147
-
148
- - [ fs2] ( https://github.com/functional-streams-for-scala/fs2 ) all the
149
- way
150
- - [ fs2-http] ( https://github.com/Spinoco/fs2-http ) for the http stack
151
- - [ doobie] ( https://github.com/tpolecat/doobie ) for db access (which
152
- uses fs2, too)
153
- - [ circe] ( https://github.com/circe/circe ) great library for json
154
- - [ pureconfig] ( https://github.com/pureconfig/pureconfig ) is reading
155
- the configuration file using
156
- [ config] ( https://github.com/typesafehub/config ) library
157
- - …
158
-
159
- See all of them in the [ libs] ( ./project/libs.scala ) file.
160
-
161
- The frontend is written in [ Elm] ( http://elm-lang.org/ ) . Two libraries
162
- aside from ` elm-lang/* ` are used:
163
-
164
- - [ evancz/elm-markdown] ( https://github.com/evancz/elm-markdown )
165
- rendering markdown
166
- - [ NoRedInk/elm-decode-pipeline] ( https://github.com/NoRedInk/elm-decode-pipeline )
167
- decoding json
168
-
169
- Non-elm components:
170
-
171
- - [ semantic-ui] ( https://semantic-ui.com ) for a well looking web
172
- interface
173
- - [ resumable.js] ( https://github.com/23/resumable.js ) for handling
174
- uploads at the client
175
-
176
- Configuring (server)
177
- --------------------
178
-
179
- Sharry reads a configuration file that can be given as an argument to
180
- the executable. Please see the
181
- [ default] ( ./modules/server/src/main/resources/reference.conf )
182
- configuration for all available options and their default values. It
183
- also contains hopefully helpful comments.
184
-
185
- For more detailed information on its syntax, please refer to the
186
- [ specification] ( https://github.com/typesafehub/config/blob/master/HOCON.md )
187
- and documentation of [ config
188
- library] ( https://github.com/typesafehub/config ) .
189
-
190
- The important settings are
191
-
192
- - ` sharry.web.bindHost ` and ` sharry.web.bindPort ` the host and port
193
- for binding the http server
194
- - ` sharry.web.baseurl ` this must be set to the external base url. So
195
- if the app is at < http://example.com/ > , then it should be set to
196
- this value. It is used to restrict the authentication cookie and to
197
- create links in the web application.
198
- - ` sharry.db.driver|user|url|password ` the JDBC settings; currently it
199
- should work with postgres and h2
200
- - ` sharry.upload.max-file-size ` maximum file size to upload
201
- - ` sharry.authc.enable=true|false ` whether to enable authentication
202
- (default is ` true ` )
203
- - ` sharry.authc.extern.admin.enable=true|false ` enables an admin
204
- account for initial login (password is ` admin ` ), default is ` false `
205
-
206
- Every setting can also be given as a Java system property by adding it
207
- to the environment variable ` SHARRY_JAVA_OPTS ` (` -D ` prefix is required
208
- here):
209
-
210
- ``` shell
211
- SHARRY_JAVA_OPTS=" -Dsharry.authc.enable=false" ./sharry-server-0.0.1-SNAPSHOT.jar.sh
212
- ```
213
-
214
- This overrides same settings in the configuration file.
215
-
216
- ### Reverse Proxy
217
-
218
- When running behind a reverse proxy, it is importand to use HTTP 1.1.
219
- For example, a minimal nginx config would look like this:
220
-
221
- ``` conf
222
- server {
223
- listen 0.0.0.0:80;
224
-
225
- proxy_request_buffering off;
226
- proxy_buffering off;
227
-
228
- location / {
229
- proxy_pass http://127.0.0.1:9090;
230
- # this is important, because fs2-http can only do 1.1
231
- # and it effectively disables request_buffering
232
- proxy_http_version 1.1;
233
- }
234
- }
235
- ```
36
+ This project is distributed under the
37
+ [ GPLv3+] ( https://spdx.org/licenses/GPL-3.0-or-later.html )
0 commit comments