view release on metacpan or  search on metacpan

lib/App/Transpierce.pm  view on Meta::CPAN

	__prod/lib__System.pm
	__prod/script.pl
	__etc__apache2/sites-available__mysite.conf

Now two local directories will be created: C<__prod> and C<__etc__apache2>.
This way the directory structure of working copies can be less chaotic by
maintaining context with a single directory for each target.

=head3 New files

It's possible to create new files:

	new 0777 user group "../file.txt"
	target ".."
		new 0777 user group "../file2.txt"

For such files:

=over

=item * they will be created (empty) in C<deploy> directory

=item * they will not exist in C<restore> directory

=item * C<deploy.sh> will create full directory path to them with default permissions

=item * C<restore.sh> will remove these files altogether (but not the directories)

=item * C<diff.sh> will C<ls -l> these files

=item * three words used after C<new> will be used for C<chmod>, C<chown> and C<chgrp> respectively and are required

=item * file permissions must be octal number in form of C<0NNN> (cannot be C<+x> for example)

=back

=head2 Scripts

C<transpierce> script is only used once during initialization. After that, work
is performed using generated shell scripts.

This design choice does two things:

=over

=item * lets you audit the contents of the files to see whether they do what is advertised and do not break anything else

=item * makes it trivial to do any modifications

=back

Both C<restore.sh> and C<deploy.sh> scripts copy each file back into their
original locations from the corresponding directory, then change their mode,
uid and gid back to what it was during the initialization. You might
B<require root permissions> to run those scripts, depending on files'
original locations and permissions.

C<diff.sh> script can be run to make sure file contents in C<restore> directory
do not differ from original files. It is recommended to do that before running
C<deploy.sh> script. If there are differences, it's possible that original
files were updated in the meantime and current working environment needs to be
initialized again.

=head2 Taking it with you

App::Transpierce was written with the ability to take it with you in mind. It
is fully compatible with perl 5.10.0, uses no non-core runtime dependencies and
is self-contained. You don't have to install the CPAN module on the target
server (which is often hard or impossible). You can instead install the module
locally, export the script and copy it into target server:

	cpanm App::Transpierce
	transpierce --self-export
	scp transpierce myuser@remote:~/transpierce

=head2 App::Transpierce and git

If the server on which you want to use the application has git, it is highly
recommended to initialize the repository and make a commit after initializing
the working environment. This lets you:

=over

=item * double-check what changes were made before running C<deploy.sh>, by running C<git diff>

=item * export the changes, for example to also apply them to the application main repository, by running C<< git diff > changes.diff >>

=item * apply diffs from outside using C<git apply changes.diff>

=item * provide more content on when was this worked on

=item * many more...

=back

=head2 Portability

This module is meant to be used on Unix (Linux, BSD) servers. No effort was
made to make it useful in other environments, mainly because the author only
knows how to administer Unix servers.

=head1 AUTHOR

Bartosz Jarzyna, E<lt>bbrtj.pro@gmail.comE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2023 by Bartosz Jarzyna

FreeBSD 2-clause license - see bundled LICENSE.