agaric/documentation
10
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

End-user documentation improvements

Browse source
This commit is contained in:
Chris Thompson 2021-07-07 18:21:21 -04:00
parent 8918395020
commit e5a33e16a7
1 changed files with 20 additions and 12 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

32
tools/drutopia-member-server-access.md
View file

@ -2,21 +2,25 @@
Agaric manages a large number of Drupal, primarily [Drutopia](https://drutopia.org/) sites on [MayFirst Movement Technology](http://mayfirst.coop) infrastructure.
For clients that require or desire access to their instance in order to perform their own backups, we provide SSH access, which includes secure transfers with sftp or scp.
For clients that require or desire access to their instance in order to perform their own backups, we provide SSH access, which includes secure transfers via sftp, scp, and rsync.
## Getting access
Access to your instance and data is make possible via SSH authentication. We only offer key-based authentication to SSH. This means you must create your own public key pair, and provide your public key to your Drutopia administrator. Once you have access via a single key, you can add additional user keys that are needed.
Access to your instance and data is made possible via SSH authentication. We only offer key-based authentication to SSH. This means you must create your own public/private key pair, and then provide your public key to your Drutopia administrator. (Once you have access via one key, you may modify the keys allowed as you need to by modifying your `~/.ssh/authorized_keys` file.)
Directions for various operating systems can be found in many places online (search "ssh keygen"). One example is at [ssh.com](https://www.ssh.com/academy/ssh/keygen). An example of other methods for Windows systems, such as [Git bash](https://docs.joyent.com/public-cloud/getting-started/ssh-keys/generating-an-ssh-key-manually/manually-generating-your-ssh-key-in-windows) are also available.
Directions for generating a key pair for various operating systems can be found in many places online (i.e. search "ssh keygen"). One example is at [ssh.com](https://www.ssh.com/academy/ssh/keygen). An example of other methods for Windows systems, such as [Git bash](https://docs.joyent.com/public-cloud/getting-started/ssh-keys/generating-an-ssh-key-manually/manually-generating-your-ssh-key-in-windows) are also available.
SSH keys come in pairs - a public and private key. Your private key is just that: private. It should not be shared outside your system. Common names for this key are, for example: id_rsa or id_ed25519. The public portion is the one you share with the administrator to be added to your account on the Drutopia host server. The public portion is typically suffixed with .pub, e.g. id_rsa.pub or id_ed25519.pub.
SSH keys come in pairs - a public and private key. Your private key is just that: private. It should not be shared outside your system. Common file names for this key are, for example: `id_rsa` or `id_ed25519`, depending on the type of key you choose to generate. The public portion is the one you share with the administrator, to be added to your account on the Drutopia host server. The public portion is typically suffixed with .pub, e.g. `id_rsa.pub` or `id_ed25519.pub`.
## Logging in
Once you have a public key configured by the Drutopia admin, you are able to connect with ssh and sftp. SSH access enables you to get a remote terminal prompt on the server to issue commands, such as attaching to your database or running drush. Your Drutopia admin will provide your user name, and the host name will match your web site's address. The convention for instances on the site is that a _test and _live user exist for each, corresponding to that instance of your site.
Once you have a public key configured by the Drutopia admin, you are able to connect with ssh and sftp. SSH access enables you to get a remote terminal prompt on the server to issue commands, such as attaching to your database or running drush. Your Drutopia admin will provide your user name, and the host name will match your web site's address. The convention for instances on the site is that an `<site>_test` and `<site>_live` user exist for each, corresponding to that instance of your site.
For example, for a site called 'example.com', you would login to: example_live@example.com.
For example, for a site called 'example.com', you might login using:
```sh
ssh example_live@example.com
```
## Common operations (drush, mysql, backups)
@ -26,21 +30,21 @@ We'll perform the two most common operations - you can enter these commands as t
A common task to perform at the prompt is to make a database backup, or to create a tarball (like a "zip file") of your files folder. This can be accomplished a few ways, but here's an example using drush to create the file `backup_db.sql.gz` in your home folder (indicated by `~`):
```
```sh
drush sql-dump --gzip --result-file=~/backup_db.sql
```
If you do not have gzip, you can omit the --gzip argument, but note the file may be significantly larger and take longer to transfer off of the system. The file created in this case will be `backup_db.sql` (i.e. no .gz at the end). Linux and Mac systems should be able to handle gzip files (gunzip <file>). For Windows systems, you might want to try [7zip](https://www.7-zip.org/).
If you do not have gzip on your system, you can omit the `--gzip` argument, but note the file may be significantly larger and take longer to transfer from the system. The file created in this case will be `backup_db.sql` (i.e. no .gz at the end). Linux and Mac systems should be able to handle gzip files (gunzip <file>). For Windows systems, you might want to try [7zip](https://www.7-zip.org/).
In order to create a single file called `backup_files.tgz` containing the full contents of your files folder:
In order to create a single file called `backup_files.tgz` in the home folder, containing the full contents of your public/uploaded files folder:
```
```sh
tar czf backup_files.tgz files/
```
Once these have been created, you can transfer them via sftp.
NOTE: Please be courteous with regard to your use of space/creation of multiple backups on this server - storage space is somewhat limited.
NOTE: Please be courteous with regard to your use of space/creation of multiple backups on this server - storage space is somewhat limited, and currently quotas are not being enforced.
## Transferring files
@ -63,4 +67,8 @@ Or, more directly with scp, download the backup file to the current directory (a
scp example_live@example.com:backup_db.sql.gz .
```
For Windows, [WinSCP](https://winscp.net/eng/index.php) is a good graphical client.
For Windows, [WinSCP](https://winscp.net/eng/index.php) is an often-recommended graphical client.
As mentioned previously, `rsync` is also available for syncing to/from the server.
Note there is little direct benefit to syncing your `~/site` folder, but this does contain the full code of the active installation. While you *can* theoretically do so, it is preferrable to work from your git source should you want to deploy your site elsewhere. Installations of Drupal on Drutopia are controlled in such a way as only certain builds of the Drutopia codebase can be installed - the contents of the site folder are not user-modifiable. ~/config and ~/site/themes/custom folders are sourced from your git repository during site install/upgrade by the Drutopia admin.