Skip to content

Commit 92d6b78

Browse files
authored
Update README.md
1 parent 3f97aa1 commit 92d6b78

File tree

1 file changed

+44
-14
lines changed

1 file changed

+44
-14
lines changed

README.md

Lines changed: 44 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
Copyright (c) 2023 The Johns Hopkins University Applied Physics
2+
Copyright (c) 2026 The Johns Hopkins University Applied Physics
33
Laboratory LLC.
44
55
This file is part of the Asynchronous Network Management System (ANMS).
@@ -21,13 +21,43 @@ subcontract 1658085.
2121
-->
2222
# AMMOS ANMS
2323

24-
This is a detailed developer-focused documentation for the AMMOS Asynchronous Network Management System (ANMS).
24+
This is the quickstart documentation for the AMMOS Asynchronous Network Management System (ANMS).
2525

2626
### Copyright
2727

28-
Copyright (C) 2022-2025 The Johns Hopkins University Applied Physics Laboratory LLC.
28+
Copyright (C) 2022-2026 The Johns Hopkins University Applied Physics Laboratory LLC.
2929

30-
[[_TOC_]]
30+
# Start Here: Which Documentation Should You Use?
31+
32+
ANMS supports multiple types of users. The appropriate documentation depends on how you are interacting with the system.
33+
34+
**1. Are you installing ANMS from this source repository?**
35+
36+
If yes, then use this README for:
37+
* Quickstart instructions
38+
* Installation steps
39+
* Basic configuration
40+
* High-level overview
41+
42+
For detailed operational guidance after installation, refer to the ANMS User Guide, found here: www.nasa-ammos.github.io/anms-docs/.
43+
44+
**2. Are you an AMMOS user or operating an already-installed ANMS instance (not from source)?**
45+
46+
If yes, do not rely on this README for operational guidance. Refer to the ANMS Product Guide and ANMS User Guide for:
47+
* System usage
48+
* Operational workflows
49+
* Configuration details
50+
51+
**NOTE:** These guides apply to *all* users once ANMS is installed.
52+
53+
**3. Are you a developer contributing to ANMS or setting up a development environment?**
54+
55+
If yes, refer to both this Readme and the ANMS Wiki – Development Guide for:
56+
* Local development environment configuration
57+
* Build instructions
58+
* Testing workflows
59+
* Contribution guidelines
60+
* Additional troubleshooting guidance
3161

3262
# Quick Start
3363

@@ -38,18 +68,18 @@ This section details prerequisites to installing the ANMS from source on a devel
3868
### Software and OS Versions
3969

4070
The setup of ANMS and demos listed in this README have been tested on macOS 11.6.4 (Big Sur), RHEL 9 and Ubuntu 20.04.
41-
To run the ANMS tool, you must also install Docker Engine version 20.10.10 or newer or Podman 5.2.2+. You will also need either Docker Compose version 1.29.2+ or podman-compose. Docker and podman can generally be used interchangeably.
71+
To run the ANMS tool, you must also install Docker Engine version 20.10.10 or newer or Podman 5.2.2+. You will also need either Docker Compose version 1.29.2+ or podman-compose. Docker and podman can generally be used interchangeably, although **please note that for Mac users, using Docker compose instead of Podman compose is generally advised to avoid inexplicable set-up errors.**
4272

43-
The ANMS UI capability has been tested on Firefox version 96.0.1.
73+
The ANMS UI capability has been tested on Firefox version 96.0.1.
4474
There is no capability that should preclude operation on other modern browsers.
4575

4676
### Network Setup
4777

4878
If your computer is behind a network proxy, this may cause issues related to using self-signed certificates when pulling dependencies to build Docker images.
49-
Though ANMS can be run behind a proxy; building the ANMS Docker images from behind a network proxy may result in errors.
79+
Though ANMS can be run behind a proxy, building the ANMS Docker images from behind a network proxy may result in errors.
5080

51-
The first steps in each of the container image `Dockerfile` is to attempt to download an APLNIS root CA to validate the APLNIS HTTPS proxy.
52-
When building images outside of the APLNIS, this download will gracefully fail and the image will not be able to run within the APLNIS. The URL for this certificate can be changed for users requiring equivalent functionality on their own networks.
81+
The first steps in each of the container image `Dockerfile` is to attempt to download the appropriate root CA to validate your HTTPS proxy.
82+
When building images outside of the internal network, it is possible that this download will gracefully fail and the image will not be able to run within the internal network. The URL for this certificate can be changed for users requiring equivalent functionality on their own networks.
5383

5484
### Special Notes on Podman
5585

@@ -62,7 +92,7 @@ Note: If running on a system where **SELinux** is enabled, the system will not s
6292

6393
### Upgrading ANMS
6494

65-
If upgrading from an earlier version, a few steps are necessary to clear out earlier state.
95+
If upgrading from an earlier version, a few steps are necessary to clear out the earlier state.
6696
The following command sequence uses standard Docker commands to stop all containers and remove all "dangling" images, networks, and volumes.
6797

6898
:warning: The last command in this sequence removes volumes, **which include DB state**.
@@ -83,12 +113,12 @@ The quickstart script will configure, pull, and start the ANMS system for the fi
83113

84114
NOTICE: By default, quick start will pull pre-built containers from the github registry (ghcr.io). To force a rebuild, run it as `FORCE_REBULD=y ./quickstart.sh`. See the script header for details.
85115

86-
To stop the system use `podman compose -f testenv-compose.yml -f docker-compose.yml down`.
116+
To stop the system, use `podman compose -f testenv-compose.yml -f docker-compose.yml down`.
87117

88-
To start the system in the future use `podman compose -f testenv-compose.yml up` and `podman compose up`.
118+
To start the system in the future, use `podman compose -f testenv-compose.yml up` and `podman compose up`.
89119

90120
## Manual Startup
91-
Choose the appropriate docker, podman or podman-compose commands in the directions below as appropriate for your system.
121+
Choose the appropriate docker, podman, or podman-compose commands in the directions below as appropriate for your system.
92122

93123
- Edit `.env` file as appropriately
94124
- Select appropriate profile(s) as desired.
@@ -112,7 +142,7 @@ Choose the appropriate docker, podman or podman-compose commands in the directio
112142
- `podman compose -f docker-compose.yml build`
113143
- `podman-compose --podman-build-args='--format docker' -f docker-compose.yml build`
114144
- Note: The docker format argument here enables suppoort for HEALTHCHECK. If omitted, the system will run but will be unable to report the health of the system. This flag does not appear necessary when using the no-dash version of compose.
115-
- Build test environemnt images using one of the following:
145+
- Build test environment images using one of the following:
116146
- `docker compose -f testenv-compose.yml build`
117147
- `podman compose -f testenv-compose.yml build`
118148
- `podman-compose --podman-build-args='--format docker' -f testenv-compose.yml build`

0 commit comments

Comments
 (0)