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

patrick-canterino.de