]> git.p6c8.net - jirafeau_project.git/blob - README.md
[BUGFIX] repair email image
[jirafeau_project.git] / README.md
1 # Jirafeau
2
3 Welcome to the official Jirafeau project, an [Open-Source software](https://en.wikipedia.org/wiki/Open-source_software).
4
5 Jirafeau is a project permitting a "one-click-filesharing", which makes it possible to upload a file in a simple way and give an unique link to it.
6
7 A demonstration of the latest version is available on [jirafeau.net](http://jirafeau.net/).
8
9 ![Screenshot1](http://i.imgur.com/TPjh48P.png)
10
11 Latest CI Status:
12 Master [![Build Status Master](https://gitlab.com/mojo42/Jirafeau/badges/master/build.svg)](https://gitlab.com/mojo42/Jirafeau/commits/master)
13 Next Release [![Build Status Next Release](https://gitlab.com/mojo42/Jirafeau/badges/test/build.svg)](https://gitlab.com/mojo42/Jirafeau/commits/master)
14 [All Branch Builds](https://gitlab.com/mojo42/Jirafeau/pipelines?scope=branches)
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 :gb: :fr: :de: :it: :nl: :ro: :sk: :hu: :cn: :gr: :ru: :es: :tk: :flag_tr:
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 System requirements:
59 - PHP >= 5.6
60 - Optional, but recommended: Git >= 2.7
61 - No database required, no mail required
62
63 Installation steps:
64 - Clone the [repository](https://gitlab.com/mojo42/Jirafeau/) or download the latest ([release](https://gitlab.com/mojo42/Jirafeau/tags) from GitLab onto your webserver
65 - Set owner & group according to your webserver
66 - A) Setup with the installation wizard (web):
67 - Open your browser and go to your installed location, eg. ```https://example.com/jirafeau/```
68 - The script will redirect to you to a minimal installation wizard to set up all required options
69 - All optional parameters may be set in ```lib/config.local.php```, take a look at ```lib/config.original.php``` to see all default values
70 - B) Setup without the installation wizard (cli):
71 - Just copy ```config.original.php``` to ```config.local.php``` and customize it
72
73 ## Upgrade
74
75 ### General procedure for all versions
76
77 1. Backup your Jirafeau installation!
78 2. Block access to Jirafeau
79 3. Checkout the new version with Git using the [tagged release](https://gitlab.com/mojo42/Jirafeau/tags)
80 * If you have installed Jirafeau just by uploading files on your server, you can download the desired version, overwrite/remove all files and chown/chmod files if needed. Keep a backup of your local configuration file tough.
81 4. With you browser, go to your Jirafeau root page
82 5. Follow the installation wizard, it should propose you the same data folder or even update automatically
83 7. Check your ```/lib/config.local.php``` and compare it with the ```/lib/config.original.php``` to see if new configuration items are available
84
85 ### From version 1.0 to 1.1
86
87 1. The download URL changed
88 * Add a rewrite rule in your web server configuration to rename ```file.php``` to ```f.php``` to make older, still existing links work again
89 1. The default theme changed
90 * Optionally change the theme in ```lib/config.local.php``` to »courgette«
91
92 ### From version 1.2.0 to 2.0.0
93
94 1. The "Terms of Service" text file changed
95 * To reuse previous changes to the ToS, move the old ```/tos_text.php``` file to ```/lib/tos.local.txt``` and remove all HTML und PHP Tags, leaving a regular text file
96
97 ### From version 2.0.0 to 3.0.0
98
99 1. No special change to upgrade to 3.0.0
100
101 ### From version 3.0.0 to 3.1.0
102
103 1. No special change to upgrade to 3.1.0
104
105 ### From version 3.1.0 to 3.2.0
106
107 1. No special change to upgrade to 3.2.0
108
109 ### From version 3.2.0 to 3.2.1
110
111 1. No special change to upgrade to 3.2.1
112
113
114 ### Troubleshooting
115
116 If you have some troubles, consider the following cases
117
118 - Check your ```/lib/config.local.php``` file and compare it with ```/lib/config.original.php```, the configuration syntax or a parameter may have changed
119 - Check owner & permissions of your files
120
121 ## Security
122
123 ```var``` directory contain all files and links. It is randomly named to limit access but you may add better protection to prevent un-authorized access to it.
124 You have several options:
125 - Configure a ```.htaccess```
126 - Move var folder to a place on your server which can't be directly accessed
127 - Disable automatic listing on your web server config or place a index.html in var's sub-directory (this is a limited solution)
128
129 If you are using Apache, you can add the following line to your configuration to prevent people to access to your ```var``` folder:
130
131 ```RedirectMatch 301 ^/var-.* http://my.service.jirafeau ```
132
133 If you are using nginx, you can add the following to your $vhost.conf:
134
135 ```nginx
136 location ~ /var-.* {
137 deny all;
138 return 404;
139 }
140 ```
141
142 You should also remove un-necessessary write access once the installation is done (ex: configuration file).
143 An other obvious basic security is to let access users to the site by HTTPS.
144
145 ## Server side encryption
146
147 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).
148 The decrypt key is not stored on the server so if you loose an url, you won't be able to retrieve file content.
149 In case of security troubles on the server, attacker won't be able to access files.
150
151 By activating this feature, you have to be aware of few things:
152 - Data encryption has a cost (cpu) and it takes more time for downloads to complete once file sent.
153 - During the download, the server will decrypt on the fly (and use resource).
154 - This feature needs to have the mcrypt php module.
155 - File de-duplication will stop to work (as we can't compare two encrypted files).
156 - Be sure your server do not log client's requests.
157 - Don't forget to enable https.
158
159 In a next step, encryption will be made by the client (in javascript), see issue #10.
160
161 ## License
162
163 GNU Affero General Public License v3 (AGPL-3.0).
164
165 The GNU Affero General Public License can be found at https://www.gnu.org/licenses/agpl.html.
166
167 Please note: If you decide do make adaptions to the source code and run a service with these changes incorporated,
168 you are required to provide a link to the source code of your version in order to obey the AGPL-3.0 license.
169 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.
170 Take a look at the FAQ to find out about how to change the ToS.
171
172 PS: If you have fixed errors or added features, then please contribute to the project and send a merge request with these changes.
173
174 ## Contribution
175
176 If you want to contribute to project, then take a look at the git repository:
177
178 - https://gitlab.com/mojo42/Jirafeau
179
180 and the Contribution Guidelines
181
182 - https://gitlab.com/mojo42/Jirafeau/blob/master/CONTRIBUTING.md
183
184 ## FAQ
185
186 ### Can I add a new language in Jirafeau?
187
188 Of course ! Translations are easy to make and no technical knowledge is required.
189
190 Simply go to [Jirafeau's Weblate](https://hosted.weblate.org/projects/jirafeau/master/).
191
192 If you want to add a new language in the list, feel free to contact us or leave a comment in ticket #9.
193
194 We would like to thank all anonymous contributors on weblate. :)
195
196 ### How do I upgrade my Jirafeau?
197
198 See upgrade instructions above.
199
200 ### How can I limit upload access?
201
202 There are two ways to limit upload access (but not download):
203 - you can set one or more passwords in order to access the upload interface, or/and
204 - 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
205
206 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).
207
208 ### How can I automatize the cleaning of old (expired) files?
209
210 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```.
211
212 Then the command can be placed in a cron file to automatize the process. For example:
213 ```
214 # m h dom mon dow user command
215 12 3 * * * www-data php /path/to/jirafeau/admin.php clean_expired
216 16 3 * * * www-data php /path/to/jirafeau/admin.php clean_async
217 ```
218
219 ### I have some troubles with IE
220
221 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).
222
223 Anyway I would recommend you to use another web browser. :)
224
225 ### How can I change the theme?
226
227 You may change the default theme to any of the existing ones or a custom.
228
229 Open your ```lib/config.local.php``` and change setting in the »`style`« key to the name of any folder in the ```/media``` directory.
230
231 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.
232
233 ### I found a bug, what should I do?
234
235 Feel free to open a bug in the [GitLab's issues](https://gitlab.com/mojo42/Jirafeau/issues).
236
237 ### How to set maximum file size?
238
239 If your browser supports HTML5 file API, you can send files as big as you want.
240
241 For browsers who does not support HTML5 file API, the limitation come from PHP configuration.
242 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.
243
244 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)
245
246 ### How can I edit an option?
247
248 Documentation of all default options are located in [lib/config.original.php](https://gitlab.com/mojo42/Jirafeau/blob/master/lib/config.original.php).
249 If you want to change an option, just edit your ```lib/config.local.php```.
250
251 ### How can I change the Terms of Service?
252
253 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)«.
254
255 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.
256
257 If you update the installation, then only the ```tos.original.txt``` file may change eventually, not your ```tos.local.txt``` file.
258
259 ### How can I access the admin interface?
260
261 Just go to ```/admin.php```.
262
263 ### How can I use the scripting interface (API)?
264
265 Simply go to ```/script.php``` with your web browser.
266
267 ### My downloads are incomplete or my uploads fails
268
269 Be sure your PHP installation is not using safe mode, it may cause timeouts.
270
271 If you're using nginx, you might need to increase `client_max_body_size` or remove the restriction altogether. In your nginx.conf:
272
273 ```nginx
274 http {
275 # disable max upload size
276 client_max_body_size 0;
277 # add timeouts for very large uploads
278 client_header_timeout 30m;
279 client_body_timeout 30m;
280 }
281 ```
282
283 ### How can I monitor the use of my Jirafeau instance?
284
285 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).
286
287 ### Why forking?
288
289 The original project seems not to be continued anymore and I prefer to add more features and increase security from a stable version.
290
291 ### What can we expect in the future?
292
293 Check [issues](https://gitlab.com/mojo42/Jirafeau/issues) to check open bugs and incoming new stuff. :)
294
295 ### What about this file deduplication thing?
296
297 Jirafeau uses a very simple file level deduplication for storage optimization.
298
299 This mean that if some people upload several times the same file, this will only store one time the file and increment a counter.
300
301 If someone use his/her delete link or an admin cleans expired links, this will decrement the counter corresponding to the file.
302
303 When the counter falls to zero, the file is destroyed.
304
305 ### What is the difference between "delete link" and "delete file and links" in admin interface?
306
307 As explained in the previous question, files with the same md5 hash are not duplicated and a reference counter stores the number of links pointing to a single file.
308 So:
309 - The button "delete link" will delete the reference to the file but might not destroy the file.
310 - The button "delete file and links" will delete all references pointing to the file and will destroy the file.
311
312 ### How to contact someone from Jirafeau?
313
314 Feel free to create an issue if you found a bug.
315
316 ## Release notes
317
318 ### Version 1.0
319
320 The very first version of Jirafeau after the fork of Jyraphe.
321
322 - Security fix
323 - Keep uploader's ip
324 - Delete link for each upload
325 - No more clear text password storage
326 - Simple langage support
327 - Add an admin interface
328 - New Design
329 - Add term of use
330 - New path system to manage large number of files
331 - New option to show a page at download time
332 - Add option to activate or not preview mode
333
334 ### Version 1.1
335
336 - New skins
337 - Add optional server side encryption
338 - Unlimited file size upload using HTML5 file API
339 - Show speed and estimated time during upload
340 - A lot of fixes
341 - A lot of new langages
342 - Small API to upload files
343 - Limit access to Jirafeau using IP, mask, passwords
344 - Manage (some) proxy headers
345 - Configure your maximal upload size
346 - Configure file's lifetime durations
347 - Preview URL
348 - Get Jirafeau's version in admin interface
349
350 ## Version 1.2.0
351
352 - Link on API page to generate bash script
353 - More informative error codes for API
354 - Security Fix: Prevent authentication bypass for admin interface
355 - CLI script to remove expired files automatically with a cronjob
356 - SHA-256 hash the admin password
357 - New theme "elegantish"
358 - Fix for JavaScript MIME-Type, prevents blocking the resource on some servers
359 - Show download link for a file in admin interface
360 - Default time for expiration (set to 'month' by default)
361 - New expiration time: 'quarter'
362 - A lof of translation contributions
363 - Code cleanups
364
365 ## Version 2.0.0
366
367 - Various documentation improvements
368 - Simplify automatic generation of local configuration file
369 - Set a custom title
370 - Bash Script: Enhanced help, show version, return link to web view as well
371 - »Terms of Service« refactored - Enable admin to overwrite the ToS, without changing existing source code → breaking, see upgrade notes
372
373 ## Version 3.0.0
374
375 - Remove XHTML doctype, support HTML5 only → breaking change for older browsers
376 - Remove redundant code
377 - Remove baseurl usage and set absolute links instead, which for example fixes SSL issues
378 - Extend contribution guide
379 - Switch to PSR-2 code style (fix line endings, indentations, whitespaces, etc)
380 - Declare system requirements
381 - Catch API errors in upload form
382 - Allow clients to upload files depending on IP or password
383 - Set UTC as timezone to prevent date/time issues
384 - Show readable date & time information
385 - Fix UI glitches in admin panel and upload form
386
387 ## Version 3.1.0
388
389 - Fix regression on user authentication (see #113)
390 - Some cosmetic change
391
392 ## Version 3.2.0
393
394 - Update translations from Update translations from weblate
395 - Better style
396 - Fix regression on admin password setting
397
398 ## Version 3.2.1
399
400 - fix download view after an upload

patrick-canterino.de