]> git.p6c8.net - jirafeau_mojo42.git/blob - README.md
[BUGFIX] Fix user/group id in Dockerfile
[jirafeau_mojo42.git] / README.md
1 # Jirafeau
2
3 ![Build Status](https://img.shields.io/gitlab/pipeline/mojo42/Jirafeau/master.svg)
4 ![Made With](https://img.shields.io/badge/made_with-php-blue.svg)
5 ![License](https://img.shields.io/badge/license-agpl--3.0-blue.svg)
6 ![Contribution](https://img.shields.io/badge/contributions_welcome-brightgreen.svg?labelColor=brightgreen)
7
8 Welcome to the official Jirafeau project, an [Open-Source software](https://en.wikipedia.org/wiki/Open-source_software).
9
10 Jirafeau is a "one-click-filesharing": Select your file, upload, share a link. That's it.
11
12 See [jirafeau.net](https://jirafeau.net/) for a demo.
13
14 ![Screenshot1](http://i.imgur.com/TPjh48P.png)
15
16 ## Main features
17
18 - One upload → One download link & one delete link
19 - Send any large files (thanks to the HTML5 file API → PHP post_max_size limit not relevant)
20 - Shows progression: speed, percentage and remaining upload time
21 - Preview content in browser (if possible)
22 - Optional password protection (for uploading or downloading)
23 - Set expiration time for downloads
24 - Option to self-destruct after first download
25 - Shortened URLs using base 64 encoding
26 - Maximal upload size configurable
27 - NO database, only use basic PHP
28 - Simple language support with a lot of langages (help us on [weblate](https://hosted.weblate.org/engage/jirafeau/)!)
29 - File level [Deduplication](http://en.wikipedia.org/wiki/Data_deduplication) for storage optimization (does store duplicate files only once, but generate multiple links)
30 - Optional data encryption
31 - Small administration interface
32 - CLI script to remove expired files automatically with a cronjob
33 - Basic, adaptable »Terms Of Service« page
34 - Basic API
35 - Bash script to upload files via command line
36 - Themes
37
38 Jirafeau is a fork of the original project [Jyraphe](http://home.gna.org/jyraphe/) based on the 0.5 (stable version) with a **lot** of modifications.
39
40 As it's original project, Jirafeau is made in the [KISS](http://en.wikipedia.org/wiki/KISS_principle) way (Keep It Simple, Stupid).
41
42 Jirafeau project won't evolve to a file manager and will focus to keep a very few dependencies.
43
44 ## Screenshots
45
46 - [Installation - Step 1](http://i.imgur.com/hmpT1eN.jpg)
47 - [Installation - Step 2](http://i.imgur.com/2e0UGKE.jpg)
48 - [Installation - Step 3](http://i.imgur.com/ofAjLXh.jpg)
49 - [Installation - Step 4](http://i.imgur.com/WXqnfqJ.jpg)
50 - [Upload - Step 1](http://i.imgur.com/SBmSwzJ.jpg)
51 - [Upload - Step 2](http://i.imgur.com/wzPkb1Z.jpg)
52 - [Upload - Progress](http://i.imgur.com/i6n95kv.jpg)
53 - [Upload - Confirmation page](http://i.imgur.com/P2oS1MY.jpg)
54 - [Admin Interface](http://i.imgur.com/nTdsVzn.png)
55
56 ## Installation
57
58 This shows how to install Jirafeau by your own, it's quite simple but you can
59 also use a [docker image](https://hub.docker.com/r/mojo42/jirafeau/) or build
60 it yourself. Check [docker folder](docker/README.md) for more informations.
61
62 System requirements:
63 - PHP >= 5.6
64 - Optional, but recommended: Git >= 2.7
65 - No database required, no mail required
66
67 Installation steps:
68 - Clone the [repository](https://gitlab.com/mojo42/Jirafeau/) or download the latest [release](https://gitlab.com/mojo42/Jirafeau/tags) from GitLab onto your webserver
69 - Set owner & group according to your webserver
70 - A) Setup with the installation wizard (web):
71 - Open your browser and go to your installed location, eg. ```https://example.com/jirafeau/```
72 - The script will redirect to you to a minimal installation wizard to set up all required options
73 - All optional parameters may be set in ```lib/config.local.php```, take a look at ```lib/config.original.php``` to see all default values
74 - B) Setup without the installation wizard (cli):
75 - Just copy ```lib/config.original.php``` to ```lib/config.local.php``` and customize it
76
77 💡 Hint: How to
78 [install & configure Jirafeau](https://www.howtoforge.com/how-to-setup-a-file-sharing-website-with-jirafeau-on-debian-10/)
79 on Debian 10 from scratch, with Nginx and PHP-FPM.
80
81 ### Troubleshooting
82
83 If you have some troubles, consider the following cases
84
85 - Check your ```/lib/config.local.php``` file and compare it with ```/lib/config.original.php```, the configuration syntax or a parameter may have changed
86 - Check owner & permissions of your files
87 - set `debug` option to `true` to check any warning or error
88
89 ## Security
90
91 ```var``` directory contains all files and links. It is randomly named to limit access but you may add better protection to prevent un-authorized access to it.
92 You have several options:
93 - Configure a ```.htaccess```
94 - Move var folder to a place on your server which can't be directly accessed
95 - Disable automatic listing on your web server config or place a index.html in var's sub-directory (this is a limited solution)
96
97 If you are using Apache, you can add the following line to your configuration to prevent people to access to your ```var``` folder:
98
99 ```RedirectMatch 301 ^/var-.* http://my.service.jirafeau ```
100
101 If you are using nginx, you can add the following to your $vhost.conf:
102
103 ```nginx
104 location ~ /var-.* {
105 deny all;
106 return 404;
107 }
108 ```
109
110 If you are using lighttpd, you can deny access to ```var``` folder in your configuration:
111
112 ```
113 $HTTP["url"] =~ "^/var-*" {
114 url.access-deny = ("")
115 }
116 ```
117
118 You should also remove un-necessessary write access once the installation is done (ex: configuration file).
119 An other obvious basic security is to let access users to the site by HTTPS (make sure `web_root` in you `config.local.php` is set with https).
120
121 ## Server side encryption
122
123 Data encryption can be activated in options. This feature makes the server encrypt data and send the decryt key to the user (inside download URL).
124 The decrypt key is not stored on the server so if you loose an url, you won't be able to retrieve file content.
125 Encryption is configured to use AES256 in OFB mode.
126 In case of security troubles on the server, attacker won't be able to access files.
127
128 By activating this feature, you have to be aware of few things:
129 - Data encryption has a cost (cpu) and it takes more time for downloads to complete once file sent.
130 - During the download, the server will decrypt on the fly (and use resource).
131 - This feature needs to have the mcrypt php module.
132 - File de-duplication will stop to work (as we can't compare two encrypted files).
133 - Be sure your server do not log client's requests.
134 - Don't forget to enable https.
135
136 In a next step, encryption will be made by the client (in javascript), see issue #10.
137
138 ## License
139
140 GNU Affero General Public License v3 (AGPL-3.0).
141
142 The GNU Affero General Public License can be found at https://www.gnu.org/licenses/agpl.html.
143
144 Please note: If you decide do make adaptions to the source code and run a service with these changes incorporated,
145 you are required to provide a link to the source code of your version in order to obey the AGPL-3.0 license.
146 To do so please add a link to the source (eg. a public Git repository or a download link) to the Terms of Service page.
147 Take a look at the FAQ to find out about how to change the ToS.
148
149 PS: If you have fixed errors or added features, then please contribute to the project and send a merge request with these changes.
150
151 ## Contribution
152
153 If you want to contribute to project, then take a look at the git repository:
154
155 - https://gitlab.com/mojo42/Jirafeau
156
157 and the Contribution Guidelines
158
159 - https://gitlab.com/mojo42/Jirafeau/blob/master/CONTRIBUTING.md
160
161 ## FAQ
162
163 ### Can I add a new language in Jirafeau?
164
165 Of course ! Translations are easy to make and no technical knowledge is required.
166
167 Simply go to [Jirafeau's Weblate](https://hosted.weblate.org/engage/jirafeau/).
168
169 If you want to add a new language in the list, feel free to contact us or leave a comment in ticket #9.
170
171 Thanks to all contributors ! :)
172
173 ### How do I upgrade my Jirafeau?
174
175 See change log and upgrade procedure in [CHANGELOG.md](https://gitlab.com/mojo42/Jirafeau/blob/master/CHANGELOG.md).
176
177 ### How can I limit upload access?
178
179 There are two ways to limit upload access (but not download):
180 - you can set one or more passwords in order to access the upload interface, or/and
181 - you can configure a list of authorized IP ([CIDR notation](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_notation)) which are allowed to access to the upload page
182
183 Check documentation of ```upload_password``` and ```upload_ip``` parameters in [lib/config.original.php](https://gitlab.com/mojo42/Jirafeau/blob/master/lib/config.original.php).
184
185 ### How can I automatize the cleaning of old (expired) files?
186
187 You can call the admin.php script from the command line (CLI) with the ```clean_expired``` or ```clean_async``` commands: ```sudo -u www-data php admin.php clean_expired```.
188
189 Then the command can be placed in a cron file to automatize the process. For example:
190 ```
191 # m h dom mon dow user command
192 12 3 * * * www-data php /path/to/jirafeau/admin.php clean_expired
193 16 3 * * * www-data php /path/to/jirafeau/admin.php clean_async
194 ```
195
196 ### I have some troubles with IE
197
198 If you have some strange behavior with IE, you may configure [compatibility mode](http://feedback.dominknow.com/knowledgebase/articles/159097-internet-explorer-ie8-ie9-ie10-and-ie11-compat).
199
200 Anyway I would recommend you to use another web browser. :)
201
202 ### How can I change the theme?
203
204 You may change the default theme to any of the existing ones or a custom.
205
206 Open your ```lib/config.local.php``` and change setting in the »`style`« key to the name of any folder in the ```/media``` directory.
207
208 Hint: To create a custom theme just copy the »courgette« folder and name your theme »custom« (this way it will be ignored by git and not overwritten during updates). You are invited to enhance the existing themes and send pull requests however.
209
210 ### I found a bug, what should I do?
211
212 Feel free to open a bug in the [GitLab's issues](https://gitlab.com/mojo42/Jirafeau/issues).
213 If you can, please copy-paste informations related to bug opening provided in admin interface.
214 Admin interface can be reached by accessing `/admin.php`.
215
216 ### How to set maximum file size?
217
218 If your browser supports HTML5 file API, you can send files as big as you want.
219
220 For browsers who does not support HTML5 file API, the limitation come from PHP configuration.
221 You have to set [post_max_size](https://php.net/manual/en/ini.core.php#ini.post-max-size) and [upload_max_filesize](https://php.net/manual/en/ini.core.php#ini.upload-max-filesize) in your php configuration. Note that Nginx setups may requiere to configure `client_max_body_size`.
222
223 If you don't want to allow unlimited upload size, you can still setup a maximal file size in Jirafeau's setting (see ```maximal_upload_size``` in your configuration)
224
225 ### How can I edit an option?
226
227 Documentation of all default options are located in [lib/config.original.php](https://gitlab.com/mojo42/Jirafeau/blob/master/lib/config.original.php).
228 If you want to change an option, just edit your ```lib/config.local.php```.
229
230 ### How can I change the Terms of Service?
231
232 The license text on the "Terms of Service" page, which is shipped with the default installation, is based on the »[Open Source Initiative Terms of Service](https://opensource.org/ToS)«.
233
234 To change this text simply copy the file [/lib/tos.original.txt](https://gitlab.com/mojo42/Jirafeau/blob/master/lib/tos.original.txt), rename it to ```/lib/tos.local.txt``` and adapt it to your own needs.
235
236 If you update the installation, then only the ```tos.original.txt``` file may change eventually, not your ```tos.local.txt``` file.
237
238 ### How can I access the admin interface?
239
240 Just go to ```/admin.php```.
241
242 ### How can I use the scripting interface (API)?
243
244 Simply go to ```/script.php``` with your web browser.
245
246 ### My downloads are incomplete or my uploads fails
247
248 Be sure your PHP installation is not using safe mode, it may cause timeouts.
249
250 If you're using nginx, you might need to increase `client_max_body_size` or remove the restriction altogether. In your nginx.conf:
251
252 ```nginx
253 http {
254 # disable max upload size
255 client_max_body_size 0;
256 # add timeouts for very large uploads
257 client_header_timeout 30m;
258 client_body_timeout 30m;
259 }
260 ```
261
262 ### How can I monitor the use of my Jirafeau instance?
263
264 You may use Munin and simple scripts to collect the number of files in the Jirafeau instance as well as the disk space occupied by all the files. You can consult this [web page](https://blog.bandinelli.net/index.php?post/2016/05/15/Scripts-Munin-pour-Jirafeau).
265
266 ### Why forking?
267
268 The original project seems not to be continued anymore and I prefer to add more features and increase security from a stable version.
269
270 ### What can we expect in the future?
271
272 Check [issues](https://gitlab.com/mojo42/Jirafeau/issues) to check open bugs and incoming new stuff. :)
273
274 ### What about this file deduplication thing?
275
276 Jirafeau uses a very simple file level deduplication for storage optimization.
277
278 This mean that if some people upload several times the same file, this will only store one time the file and increment a counter.
279
280 If someone use his/her delete link or an admin cleans expired links, this will decrement the counter corresponding to the file.
281
282 When the counter falls to zero, the file is destroyed.
283
284 In order to know if a newly uploaded file already exist, Jirafeau will hash the file using md5 by default but other methods are available (see `file_hash` documentation in `lib/config.original.php`).
285
286 ### What is the difference between "delete link" and "delete file and links" in admin interface?
287
288 As explained in the previous question, files with the same hash are not duplicated and a reference counter stores the number of links pointing to a single file.
289 So:
290 - The button "delete link" will delete the reference to the file but might not destroy the file.
291 - The button "delete file and links" will delete all references pointing to the file and will destroy the file.
292
293 ### How to contact someone from Jirafeau?
294
295 Feel free to create an issue if you found a bug.
296
297 Also, you can come have a chat on [libera.chat](https://web.libera.chat/) in `#jirafeau` channel.
298
299 ### Can I buy you a coffee?
300
301 You can [drop few bucks](https://www.paypal.com/paypalme/jeromejutteau) to help the [demo web site](https://jirafeau.net) to stay alive.

patrick-canterino.de