NOTE: There is an updated version of this document available here: https://docs.google.com/document/d/1DdSK-G4R0we8YcalPJNC12XgcCc-9baefXdjFyPvvF0/edit?usp=sharing
Please update your links!
All Premium+ clients get SSH access to the server hosting their AtoM instance. Listed below is information on how to get started using an SSH client to connect to the server, and issue various CLI (command line interface) commands.
Windows: We recommend using PuTTY as a client if you are connecting from Windows. You can find tutorials online such as this one to get started.
Linux: Most Linux distributions (such as Ubuntu) come with an ssh client
pre-installed. Please consult your particular Linux distribution's documentation
for further details if you need to install an ssh client. Generally, all you
need to do is issue a command such as ssh myusername@1.2.3.4 to
connect, where myusername is the username you were given, and 1.2.3.4 is
replaced with the IP address to your server.
When your AtoM install is ready, you should be given the proper ssh credentials to login successfully. If you haven't received credentials yet, you can contact Artefactual for the information.
If you are unfamiliar with basic Linux commands, you can consult this page to get a very basic introduction.
A quick search for "Linux command-line cheat sheet" will return many options, including:
- A PDF hosted by Tufts University: http://sites.tufts.edu/cbi/files/2013/01/linux_cheat_sheet.pdf
- Another PDF cheat sheet, with translations in multiple languages: http://fosswire.com/post/2007/08/unixlinux-command-cheat-sheet/
- A tutorial and a link to a free book: http://linuxcommand.org/
- Joshua Levy has created a very popular guide, 'The Art of the Command-line', available here: https://github.com/jlevy/the-art-of-command-line
And so forth.
The AtoM install location will be /usr/share/nginx/atom unless
otherwise specified. Example of how to change directories to get there, to the
root directory of your AtoM installation:
cd /usr/share/nginx/atom
If you have any issues accessing your AtoM instance at this location, please contact us and we will be happy to assist you.
To run AtoM command line tasks, you will generally need to
cd /usr/share/nginx/atom and then issue commands such as
php symfony example:task <arguments here>.
We have thorough documentation with details on various AtoM maintenance tasks and what their parameters and options are. Furthermore, we have specific documentation for users wanting to import and export data to and from AtoM.
Here are some of the most useful links:
- Command-line tools: https://www.accesstomemory.org/docs/2.1/admin-manual/maintenance/cli-tools/
- CSV import documentation: https://accesstomemory.org/docs/2.1/user-manual/import-export/csv-import/
Examples of what you will find in the command-line tools documentation:
- Bulk import and bulk export from the command-line (EAD, MODS, or DC XML)
- How to create a new admin user from the command-line, or change the password of an existing user
- How to re-index text extracted from your PDFs so it is in the search index
- How to regenerate slugs
- Deleting a large description from the command-line
- Updating the publication status of draft records
- Common AtoM database queries
And more! For the full list, see:
Other useful maintenance documentation:
- Rebuilding the search index: https://accesstomemory.org/docs/2.1/admin-manual/maintenance/populate-search-index/
- Clearing the application cache: https://accesstomemory.org/docs/2.1/admin-manual/maintenance/clear-cache/
- Manage AtoM configuration files: https://accesstomemory.org/docs/2.1/admin-manual/customization/config-files/
Client sessions in Premium+ are automatically created inside tmux sessions, and hence are persistent. This means for example if you disconnect accidentally in the middle of an import or export task in AtoM, that task will still run in the background while you aren't logged in. When you log back in later, you should then see your previous session's screen restored. This feature should be transparent for the user and not require any further setup. For more technical information on tmux, see here.
If you want to know more about tmux in general, see also:
If you have a general question about AtoM, our CLI tasks, CSV import, or the like, please consider posting in our User Forum:
By asking your question in the public forum, there are a number of benefits for you and the community as a whole:
- If you're not certain about something, it's almost guaranteed that someone else out there has the same question!
- Whenever Artefactual answers in the public forum it helps all users.
- Similar questions in the future can be directed to the thread you start; other users searching the user forum can find your answer instead of having to post again
- Other users might have answers or workarounds that we had not considered! By posting in the user forum, you get many eyes on the issue
- Reports from other users can help us determine if you've uncovered a bug in AtoM, or a spot where our documentation is unclear
- It helps to build a sense of community, participation, and ownership among community members - and the stronger the community, the stronger the AtoM project is!
More information about our user forum, and how to make a post:
If you have a question or issue specific to your AtoM instance you can contact Artefactual directly by emailing support@artefactual.com