S3Share User Manual

How to sign in, find and write documents, attach files, and — for administrators — how to set up users, territories, permissions and the S3 connection.

Getting started

What S3Share does

S3Share keeps your organization's documents in one place: a short page of text written in the browser, plus any number of attached files stored in an Amazon S3 bucket. Documents live inside territories and folders, and every document carries an access level from 1 to 10. You see a document when your level in that territory is at least the document's level.

The four ideas to know

Idea	What it means
Territory	A top-level container such as a region, office or department. Every document belongs to exactly one territory. A territory has a short code that becomes the top folder in the S3 bucket.
Membership, level and manager	An administrator adds you to a territory with a level (1–10). Territory managers see everything in the territory and may move, archive, unarchive and delete any document, and manage its folders.
Document	A title, a formatted body with inline images, and attachments. It is created as a draft, then published, and later archived. Only the author edits it; others may copy it.
Audit	Every change is written to the system log and every read or download of a document is recorded, so administrators can answer "who did what, when".

Getting started

Signing in

Open the address your administrator gave you and enter your username and password. If two-factor sign-in is turned on for your account, a six-digit code is emailed to you and must be entered on the next screen before you reach Home.

The sign-in page. Tick Remember me to keep your username on this device.

Two-factor step: enter the emailed code, or ask for a new one.

First sign-in and password reset

New accounts have no password yet. Choose your first password from the link in the email your administrator sends, or press Forgot password? on the sign-in page and enter your email address to receive a code. After five wrong passwords or codes, sign-in is paused for 15 minutes.

Choose a new password: at least 8 characters with an upper-case letter, a digit and a special character.

If you no longer receive the email, ask your administrator to open Configuration › Users, check your email address and press Send reset link.

Getting started

The Home screen

Home has three parts: the dark side menu on the left, a tab bar across the top, and the work area below it. Everything you open becomes a tab, so you can keep several documents and pages side by side.

Side menu with the territory tree and page links; open items appear as tabs.

Part	What it does
Territory tree	Lists the territories you belong to. Expand one to see its folders — only folders that contain something you may read are shown; managers see every folder. Click a territory or folder to list its documents in the Browser.
Page links	Dashboard, Documents, Configuration and Report, depending on your role. Each opens once as a tab; clicking again returns to it.
Search icon	Type a word to see the first matches instantly; press Enter to open the full Search tab with filters and paging.
? button	Opens this manual in a new browser tab.
Document tabs	Each document opens in its own tab. Up to 7 documents can be open at once (the limit is set in Options); close one before opening more. Tabs can be dragged to reorder.
Your name	Opens the user menu: My Profile, Change Password and Log Out.

On a phone the side menu becomes a drawer behind the ☰ button and a bottom bar gives you Home and Search. Tablets keep the menu, which can be collapsed to icons.

Documents

Browser

Documents › Browser lists the documents of the folder selected in the side menu. The breadcrumb at the top shows where you are; the chips next to it show your level (L1–L10) and MGR if you manage the territory.

A folder listing. Hover a row for its actions; click the row to open the document.

Finding documents

Type in the search box, choose where to look — Title, Body or Author — pick a status, and press Search or Enter. Column headers sort; the pager at the bottom moves through pages of 20. Excel downloads the current folder as a CSV file.

Creating a document

Press + New Document. A draft called "Untitled document" is created in the current folder and opens in a new tab already in edit mode, with the title selected. Drafts are visible only to you and the territory managers. If you close or cancel the new draft before typing anything, it is removed again.

Folders

The Folder ▾ menu is for territory managers. Folders can be nested up to seven levels deep; names may contain letters, digits, spaces and - _ . ( ).

The Folder menu: new subfolder, rename, move, delete.

Action	Effect
New subfolder	Creates a folder under the current one.
Rename folder	Renames it; file locations in S3 are moved to match.
Move folder	Moves the folder and everything inside it under another folder (or the territory root) of the same territory. A folder cannot be moved into itself.
Delete folder	Removes the folder, its subfolders and their documents. With the Trash turned on the documents go to the Trash; otherwise they are removed immediately.

Documents

Working on a document

A document opens in its own tab. The header shows the territory and folder, the status, level, version, author and dates, and the buttons: Edit, Publish, More ▾, Print and ✕ (close tab). The body is below; the description and the attachments are on the right.

Reading a published document. Attachments download with the arrow button.

Print opens a clean copy of the document — title, path, status line, description, body with pictures and the attachment names — in a new window and shows the print dialog. ✕ closes the tab; while editing it asks first if there are unsaved changes.

Editing

Only the author sees Edit, and only while the document is a draft or published. In edit mode the title becomes a field, a level selector appears (you cannot set a level above your own), the formatting toolbar is shown, and the Description box on the right becomes editable (up to 1000 characters; it is shown as a tooltip in lists and is searched together with the body). Save stores the text; Cancel throws away unsaved changes after a confirmation.

Edit mode: title, level, toolbar, description, a selected picture with its resize handle, and the attachment drop zone.

Pictures in the text

Action	How
Insert	Toolbar image button, or paste a picture from the clipboard (screenshot, copied image) with Ctrl+V. Either way the picture is uploaded as an attachment and placed at the cursor.
Resize	Click the picture: an outline, a size label and a round handle at the bottom-right corner appear. Drag the handle; the proportions are kept and the picture cannot be wider than the text area. The size is saved with the document.
Remove	Click the picture and press Delete (or remove its attachment on the right). Esc deselects.

Toolbar	Use
Paragraph ▾	Paragraph, three heading sizes or a quote block for the current line.
B I U S	Bold, italic, underline, strikethrough.
Lists and alignment	Bulleted or numbered lists; left, center, right.
Link	Turns the selected text into a link. Links open in a new window when reading.
Insert image	Uploads a picture and places it at the cursor. It is also listed as an attachment.
Rule, clear, undo, redo	Horizontal rule; remove formatting from the selection; undo and redo.

Pasted text is inserted as plain text, so copying from Word or a web page does not bring hidden formatting with it.

The More menu

Move, Copy, Archive, Delete, Refresh and Close tab.

Action	Who	What happens
Publish	Author of a draft	Makes the document visible to everyone in the territory with the required level. The version becomes 1.
Archive	Author or manager, published only	Freezes the document: no more editing, attachments cannot change.
Unarchive	Manager	Returns an archived document to published so the author can edit again.
Move	Author (draft/published) or manager (any)	Moves the document to another folder of the same territory. Files are moved in S3 as well.
Copy	Anyone who can read it	Creates a new draft owned by you, in any territory you belong to, titled "Copy of …". The level is lowered to yours if needed. Copies of archived documents do not carry attachments.
Delete	Author (draft/published) or manager (any)	Sends the document to the Trash, or removes it permanently when the Trash is turned off.

Documents

Attachments and images

Attachments are uploaded straight from your browser into the S3 bucket through a short-lived signed link; the file never passes through the web server, so large files upload quickly. In edit mode press + Add attachment and pick one or more files, or drag files from your computer onto the attachment list (it shows a dashed outline while you drag). Watch the progress bar; a file is listed only once the upload is complete.

Rule	Detail
Allowed types	Only the extensions listed under Configuration › Options › Allowed file types. The hint under the Add button shows them.
Size	Each type has its own maximum in MB, capped by the application-wide MaxUploadMB setting.
Images	PNG and JPEG pictures inserted into the text are stored like any other attachment and shown inline. Removing the attachment removes the picture from the text.
Downloads	The arrow button creates a signed link valid for a few minutes (LinkMinutes in Options) and opens it. Each download is recorded in the audit trail.
Storage layout	Files are stored as `territory-code/folder/path/document-id/file-id.ext`, so the bucket mirrors the folder tree and can be browsed with normal AWS tools.

If a download opens nothing, your browser blocked the pop-up. Allow pop-ups for the S3Share address and try again; a direct link is offered in the message.

Documents

Draft, published, archived

Status	Who sees it	Editing	Attachments
Draft	Author and territory managers	Author	Author adds and removes
Published	Everyone in the territory with level ≥ document level, plus managers	Author; each save raises the version	Author adds and removes
Archived	Same readers as published	Nobody until a manager unarchives	Frozen; copies are made without attachments
Trash	Author and managers, in Documents › Trash	—	Kept until purged

Documents

Who can do what

Reading depends on the rule above. Changing a document depends on who you are and on its status:

	Author	Territory manager	Other member
Open and read	always	always	published / archived at or below my level
Edit text, level, attachments	draft, published	—	—
Publish	draft	—	—
Archive	published	published	—
Unarchive	—	archived	—
Move	draft, published	any status	—
Copy	any readable	any readable	any readable
Delete	draft, published	any status	—
Folders: create, rename, move, delete	—	yes	—
Trash: restore, delete forever	own documents	any in the territory	—

In addition to these rules, each button is only shown when your role grants the matching action (see Roles and permissions). A missing button usually means the role, not the document, is the reason.

Documents

Search

Documents › Search looks across every territory you belong to. Choose Title + Body, Title, Body or Author, narrow by territory and status, and press Search. Results respect your level in each territory. Click a row to open the document; Excel exports the result.

Documents

Trash

When the Trash is turned on (Options › TrashUse), deleted documents wait in Documents › Trash. You see your own deleted documents and, as a manager, every deleted document of your territories. The note at the top tells how many days a document stays before it is removed automatically.

Restore puts a document back where it was; Delete forever removes it and its files.

Button	Effect
Restore	Returns the document to its folder with the status it had (draft, published or archived). If the folder no longer exists it goes to the territory root.
Delete forever	Removes the record and its files from S3. This cannot be undone.
Empty Trash	Deletes forever every document in the list you are allowed to remove, optionally limited to the selected territory.

Dashboard and reports

Dashboard

The Dashboard summarizes what you can see: document counts, how many you authored, your territories, storage used, reads and downloads over the last 30 days and what is waiting in the Trash. The chart shows the last 14 days of changes, reads and downloads; the lists open documents directly. Press Refresh for current numbers.

Dashboard and reports

Audit report

Report › Audit is the trail of everything that happened. Switch the first dropdown between two sources:

Source	Contents
System changes	Every write made through the application: who, when, from which address, which page and method, and the SQL statement with its parameters (passwords and the S3 secret are never recorded).
Document access	Every read of a document and every file download, with the user, document, territory, file and address.

Filter by text and field, pick a date range (default: the last seven days), sort by clicking a header, and click a row for the full entry. Excel exports up to 10,000 rows of the current filter.

System changes with the detail of one entry.

Configuration

Users

Configuration › Users lists accounts with their roles, territories, two-factor setting and status. Click a row to open the review panel.

The user panel: identity, roles, and the territory table with level and manager per territory.

Field	Meaning
Status	Active can sign in. Inactive and Suspended cannot; their documents stay.
Two-factor sign-in	Off, or Email code: a six-digit code is emailed at every sign-in.
Roles	One or more roles. Roles decide which pages and buttons the user gets.
Territories	Tick Member, pick the Level (1–10) and optionally Manager for each territory the user should see.
Change photo	A PNG or JPEG up to 5 MB shown next to the name.

New user

Press + New user, enter the name, username and email. No password is set: press Send reset link so the person can choose one from the email (or they use Forgot password?). Until then the account cannot be used. Roles and territories are assigned afterwards in the panel.

Send reset link

Flags the account and emails a link that is valid for 30 minutes. Use it when someone is locked out.

You cannot deactivate or delete your own account, and the last active Administrator cannot lose that role.

Configuration

Roles and permissions

A role is a named set of permissions. S3Share ships with Administrator (everything), Manager (everything except Configuration) and User. Add roles in Configuration › Roles; a role in use by users cannot be deleted.

In Configuration › Permissions pick a role in the left list. The right side shows every page; open a page to see its tabs, open a tab to see its action buttons, and switch each one On or Off. Turning a page off turns off everything under it; turning an action on turns on its tab and page. The small text next to an action lists the server methods it unlocks. Changes are collected (the role shows a dot and the header counts them) until you press Review & Save, which lists every change as Was → Now before you confirm; Discard drops them. Users see the result at their next sign-in or page refresh.

Permissions: role list, page › tab › action switches, unsaved-changes badge.

The Administrator role always keeps the Configuration page, its Permissions tab and the Review & Save action, so nobody can lock everyone out.

Configuration

Pages

Configuration › Pages shows the registry the permission system is built on: pages, their tabs and the actions with their method names. It is mostly reference; change it only when new functionality has been added to the application, because a tab needs matching code before it shows anything.

Configuration

Territories

Create territories in Configuration › Territories. The code (lowercase letters, digits and dashes) becomes the top folder in the S3 bucket and cannot change once the territory has documents. Inactive territories disappear from everyone's side menu but keep their data. A territory can be deleted only when it has no documents, including the Trash.

Configuration

Options and S3

Configuration › Options holds the application-wide settings.

Application values, S3 connection, allowed file types and access-level names.

Setting	Meaning
Name	The application name shown on the sign-in page, in the side menu and in emails.
Email, Phone, Address	Company contact details.
TimeOffset	Hours added to the server time when showing dates.
TrashUse / TrashDays	1 keeps deleted documents in the Trash for TrashDays days; 0 deletes immediately.
MaxUploadMB	Largest single upload, in MB. Each file type may set a lower limit.
MaxDepth	Maximum folder depth under a territory (up to 7).
LinkMinutes	How long a download link stays valid.
DocTabs	How many document tabs may be open at once.

Amazon S3

Enter the IAM access key, secret key, bucket name and region, press Save, then Test connection. The secret is stored only in the database, is never shown again and is read fresh for every request, so rotating keys needs no restart. The IAM user needs s3:GetObject, s3:PutObject, s3:DeleteObject on the bucket's objects and s3:ListBucket on the bucket.

Because browsers upload directly to the bucket, the bucket needs a CORS rule that allows PUT, GET and HEAD from every address S3Share is used at (scheme, host and port — add the production address when you deploy). The normal way is to paste data/s3-cors.json under the bucket's Permissions › Cross-origin resource sharing in the AWS console and replace the placeholder with your real address. Alternatively, if the IAM user is also granted s3:GetBucketCORS and s3:PutBucketCORS, the button Allow uploads from this address adds the current address to the rule for you; Test connection then lists the allowed addresses.

Allowed file types and level names

Add or edit file types with their extension, content type, kind (Image, Office, PDF, Other) and size limit; removing a type stops new uploads but keeps existing files. The ten access levels can be given names such as "Staff", "Lead" or "Director" — they appear in every level dropdown.

Run mode

The chip next to Application shows the run mode, which is set in appConfig/application.cfg (app.app.runmode): 0 Demo, 1 Production, 2 Archive. In Archive mode every write is refused and a banner is shown, which is useful before a migration.

Sample data

The optional script sql/S3Share_08_Seed.sql adds two more territories (West Region, Raleigh Office), the users jane (Manager), tom, ana and sam with territory levels, a few folders and documents. The new users have no password yet: send each a reset link from Configuration › Users. Run it only on a test or new installation.

Reference

Profile and password

Open your name at the bottom of the side menu. My Profile lets you change your name, email, phone and photo and shows your territories with your level in each. Change Password asks for the current password and a new one that meets the rules. Log Out ends the session.

My Profile.

Reference

Setup checklist

For the person installing S3Share.

Step	Where
1. Create the database with the scripts in `sql/` in numeric order	SQL Server
2. Point `app.sqldb.` at the database and fill `app.mail.` so verification and reset emails can be sent	appConfig/application.cfg
3. Set `app.app.runmode` to 1 for production	appConfig/application.cfg
4. Sign in as admin (any password) and set the real password	Sign-in page
5. Enter the S3 keys, bucket and region and press Test connection	Configuration › Options
6. Apply the CORS rule from `data/s3-cors.json` to the bucket, or press Allow uploads from this address in Options if the IAM user may change bucket CORS	AWS console
7. Create territories, then users with their levels	Configuration › Territories, Users
8. Review file types and the Trash settings	Configuration › Options

Reference

FAQ

Question	Answer
I cannot see a document a colleague mentioned.	Either its level is above yours in that territory, it is still a draft (only the author and managers see drafts), or you are not a member of the territory. Ask a manager or administrator.
The Edit button is missing.	Only the author can edit, and only while the document is a draft or published. Archived documents must be unarchived by a manager first. Copy the document if you need your own version.
My upload is refused.	Check the file extension against the allowed types and its size against the limit shown under the Add button.
The upload says the browser could not reach the bucket.	The bucket has no CORS rule for this address, or the bucket name or region in Options is wrong. See Options and S3.
Can I paste a screenshot?	Yes — in edit mode press Ctrl+V with the picture in the clipboard; it is uploaded and placed at the cursor. Click it afterwards to resize.
Why can I not open an eighth document?	The tab limit (Options › DocTabs) is reached. Close a document tab first.
Can a document be in two territories?	No. A document belongs to one territory; use Copy to place an independent copy elsewhere.
Where are the files physically?	In the S3 bucket, under territory-code/folder/document-id/. The database keeps the original file names; the bucket uses ids.
Something was deleted by mistake.	Look in Documents › Trash and press Restore. After the Trash period, or when the Trash is turned off, the administrator must restore from bucket versioning or backups.