Skip to content

Commit

Permalink
adding docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@freekmurze
freekmurze committed Feb 17, 2016
1 parent cd16536 commit eacbb3c
Show file tree
Hide file tree
Showing 9 changed files with 320 additions and 18 deletions.
1 change: 0 additions & 1 deletion .gitignore
View file
@@ -1,4 +1,3 @@
build
composer.lock
docs
vendor
31 changes: 14 additions & 17 deletions config/laravel-backup.php
View file
Expand Up @@ -6,7 +6,7 @@

/*
* The name of this application. You can use this name to monitor
* the backups
* the backups.
*/
'name' => env('APP_URL'),

Expand Down Expand Up @@ -50,14 +50,6 @@
'filesystems' => [
'local'
],

/*
* By default the backups will be stored as a zipfile with a
* timestamp as the filename. With these options You can
* specify a prefix and a suffix for the filename.
*/
'prefix' => '',
'suffix' => config('app.name'),
],
],

Expand All @@ -71,17 +63,17 @@
'defaultStrategy' => [

/*
* The amount of days that daily backups must be kept
* The amount of days that all daily backups must be kept.
*/
'keepDailyBackupsForDays' => 16,

/*
* The amount of weeks of which one weekly backup must be kept
* The amount of weeks of which one weekly backup must be kept.
*/
'keepWeeklyBackupsForWeeks' => 8,

/*
* The amount of months of which one monthly backup must be kept
* The amount of months of which one monthly backup must be kept.
*/
'keepMonthlyBackupsForMonths' => 4,

Expand All @@ -106,17 +98,20 @@
*/
'monitorBackups' => [
[
'name' => 'spatie.be',
'name' => env('APP_URL'),
'filesystems' => ['local'],
'newestBackupsShouldNotBeOlderThanDays' => 1,
'storageUsedMayNotBeHigherThanMegabytes' => 5000,
],

/*
[
'name' => 'laravel.com',
'filesystems' => ['local', 's3'],
'name' => 'name of the second app',
'filesystems' => ['local'],
'newestBackupsShouldNotBeOlderThanDays' => 1,
'storageUsedMayNotBeHigherThanMegabytes' => 5000,
],
*/
],

'notifications' => [
Expand All @@ -129,6 +124,8 @@
/*
* Here you can specify the ways you want to be notified when certain
* events take place. Possible values are "log", "mail" and "slack".
*
* Slack requires the installation of the maknz/slack package
*/
'events' => [
'whenBackupWasSuccessful' => ['log'],
Expand All @@ -143,8 +140,8 @@
* Here you can specify how mails should be sent.
*/
'mail' => [
'from' => 'freek@spatie.be',
'to' => 'freek@spatie.be',
'from' => 'your@email.com',
'to' => 'your@email.com',
],

/*
Expand Down
13 changes: 13 additions & 0 deletions docs/about-us.md
View file
@@ -0,0 +1,13 @@
---
title: About us
---
[Spatie](https://spatie.be) is a webdesign agency based in Antwerp, Belgium.

Open source software is used in all projects we deliver. Laravel, Nginx, Ubuntu are just a few
of the free pieces of software we use every single day. For this, we are very grateful.
When we feel we have solved a problem in a way that can help other developers,
we release our code as open source software [on GitHub](https://spatie.be/opensource).

This backup package was made by [Freek Van der Herten](https://twitter.com/freekmurze). There are
[many other contributors](https://github.com/spatie/laravel-medialibrary/graphs/contributors) who devoted
a bit of time and effort to make this package better.
5 changes: 5 additions & 0 deletions docs/changelog.md
View file
@@ -0,0 +1,5 @@
---
title: Changelog
---

TO DO
23 changes: 23 additions & 0 deletions docs/high-level-overview.md
View file
@@ -0,0 +1,23 @@
---
title: High level overview
---

The backup package can perform 3 tasks:

## Take backups

The backup is a zipfile that contains all files in the directories you specify along with a dump of your database.
This zipfile can automatically be copied over to [any of the filesystems you have configured in Laravel 5](http://laravel.com/docs/5.0/filesystem).

To take a command you can run `php artisan backup:run`. In most cases you want to schedule this command.

## Clean up old backups

If you keep on taking backups eventually you'll run out of disk space (or you'll have to big a very large bill
for storage). To prevent this from happening the package can clean up old backups.

## Monitor the health of all backups

Optionally the package can check the health of your applications. A backup is considered unhealty if
the date of the last backup is too far in the past of if the backup becomes too large. In addition to
monitoring the health of the application's own backups, backups of other applications can be monitored as well.
212 changes: 212 additions & 0 deletions docs/installation-and-setup.md
View file
@@ -0,0 +1,212 @@
---
title: Installation & setup
---

## Basic installation

You can install this package via composer using:

``` bash
composer require spatie/laravel-backup
```

You must also install this service provider.

```php

// config/app.php

'providers' => [
...
'Spatie\Backup\BackupServiceProvider',
...
];
```

To publish the config file to ``app/config/laravel-backup.php`` run:

``` bash
php artisan vendor:publish --provider="Spatie\Backup\BackupServiceProvider"
```

This is the default contents of the configuration.

```php
<?php

return [

'backup' => [

/*
* The name of this application. You can use this name to monitor
* the backups.
*/
'name' => env('APP_URL'),

'source' => [

'files' => [

/*
* The list of directories that should be part of the backup. You can
* specify individual files as well.
*/
'include' => [
base_path(),
],

/*
* These directories will be excluded from the backup.
* You can specify individual files as well.
*/
'exclude' => [
base_path('vendor'),
storage_path(),
],
],

/*
* The names of the connections to the databases
* that should be part of the backup.
*/
'databases' => [
'mysql'
],
],

'destination' => [

/*
* The filesystems you on which the backups will be stored. Choose one or more
* of the filesystems you configured in app/config/filesystems.php
*/
'filesystems' => [
'local'
],
],
],

'cleanup' => [
/*
* The strategy that will be used to cleanup old backups.
* The youngest backup wil never be deleted.
*/
'strategy' => \Spatie\Backup\Tasks\Cleanup\Strategies\DefaultStrategy::class,

'defaultStrategy' => [

/*
* The amount of days that all daily backups must be kept.
*/
'keepDailyBackupsForDays' => 16,

/*
* The amount of weeks of which one weekly backup must be kept.
*/
'keepWeeklyBackupsForWeeks' => 8,

/*
* The amount of months of which one monthly backup must be kept.
*/
'keepMonthlyBackupsForMonths' => 4,

/*
* The amount of years of which one yearly backup must be kept
*/
'keepYearlyBackupsForYears' => 2,

/*
* After clean up the backups remove the oldest backup until
* this amount of megabytes is reached.
*/
'deleteOldestBackupsWhenUsingMoreMegabytesThan' => 5000
]
],


/*
* In this array you can specify which backups should be monitored.
* If a backup does not meet the specified requirements the
* UnHealthyBackupWasFound-event will be fired.
*/
'monitorBackups' => [
[
'name' => env('APP_URL'),
'filesystems' => ['local'],
'newestBackupsShouldNotBeOlderThanDays' => 1,
'storageUsedMayNotBeHigherThanMegabytes' => 5000,
],

/*
[
'name' => 'name of the second app',
'filesystems' => ['local'],
'newestBackupsShouldNotBeOlderThanDays' => 1,
'storageUsedMayNotBeHigherThanMegabytes' => 5000,
],
*/
],

'notifications' => [

/*
* This class will be used to send all notifications.
*/
'handler' => Spatie\Backup\Notifications\Notifier::class,

/*
* Here you can specify the ways you want to be notified when certain
* events take place. Possible values are "log", "mail" and "slack".
*
* Slack requires the installation of the maknz/slack package
*/
'events' => [
'whenBackupWasSuccessful' => ['log'],
'whenCleanupWasSuccessful' => ['log'],
'whenHealthyBackupWasFound' => ['log'],
'whenBackupHasFailed' => ['log', 'mail'],
'whenCleanupHasFailed' => ['log', 'mail'],
'whenUnHealthyBackupWasFound' => ['log', 'mail']
],

/*
* Here you can specify how mails should be sent.
*/
'mail' => [
'from' => 'your@email.com',
'to' => 'your@email.com',
],

/*
* Here you can how messages should be sent to Slack.
*/
'slack' => [
'channel' => '#backups',
'username' => 'Backup bot',
'icon' => ':robot:',
],
]
];
```

## Scheduling

After you have performed the basic installation you can using the `backup:run`, `backup:clean`,
`backup:overview` and `backup:monitor`-commands. In most cases you want to scheduled these commands
so you don't have to run `backup:run` everytime you need a new backup.

The commands can, like an other command, be scheduled in Laravel's console kernel.

```php
//app/Console/Kernel.php

protected function schedule(Schedule $schedule)
{
$schedule->command('backup:clean')->daily()->at('01:00');
$schedule->command('backup:run')->daily()->at('02:00');
$schedule->command('backup:monitor')->daily()->at('03:00');
}
```

Of course, the hours used in the code above are just examples. Adjust them to your own liking.
28 changes: 28 additions & 0 deletions docs/introduction.md
View file
@@ -0,0 +1,28 @@
---
title: Introduction
permalink: /
---

<section class="badges">
<a href="https://github.com/spatie/laravel-backup/releases"><img src="https://img.shields.io/github/release/spatie/laravel-backup.svg?style=flat-square" alt="Latest Version"></a>
<a href="LICENSE.md"><img src="https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square" alt="Software License"></a>
<a href="https://travis-ci.org/spatie/laravel-backup"><img src="https://img.shields.io/travis/spatie/laravel-backup/master.svg?style=flat-square" alt="Build Status"></a>
<a href="https://insight.sensiolabs.com/projects/xxxx"><img src="https://img.shields.io/sensiolabs/i/xxxx.svg?style=flat-square" alt="SensioLabsInsight"></a>
<a href="https://scrutinizer-ci.com/g/spatie/laravel-backup"><img src="https://img.shields.io/scrutinizer/g/spatie/laravel-backup.svg?style=flat-square" alt="Quality Score"></a>
<a href="https://packagist.org/packages/spatie/laravel-backup"><img src="https://img.shields.io/packagist/dt/spatie/laravel-backup.svg?style=flat-square" alt="Total Downloads"></a>
</section>


This Laravel 5 package creates a backup of your application. The backup is a zipfile that contains all files in the directories you specify along with a dump of your database.
The backup can be stored on [any of the filesystems you have configured in Laravel 5](http://laravel.com/docs/5.0/filesystem).

Feeling paranoid about backups? No problem! You can backup your application to multiple filesystems at once.

Once installed taking a backup of your files and databases is very easy. Just issue this artisan command:

``` bash
php artisan backup:run
```

In addition to taking the backup the package can also clean up old backups, monitor the health of the backups
and show an overview of all backups.
10 changes: 10 additions & 0 deletions docs/questions-and-issues.md
View file
@@ -0,0 +1,10 @@
---
title: Questions & issues
---

Find yourself stuck using the package? Found a bug? Do you have general questions or suggestions for
improving the backup package? Feel free to [create an issue on GitHub]
(https://github.com/spatie/laravel-medialibrary/issues), we'll try to address it as soon as possible.

If you've found a bug regarding security please mail [freek@spatie.be](mailto:freek@spatie.be) instead
of using the issue tracker.

0 comments on commit eacbb3c

Please sign in to comment.