commit cd47fc8dd7bed6e96de3349b14ce5cd78e845795 Author: Alexander Wang Date: Tue Nov 1 13:31:39 2022 -0700 oss diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..f2f29e6 --- /dev/null +++ b/LICENSE @@ -0,0 +1 @@ +TALA is currently closed-source. For more information on licensing, please visit https://terrastruct.com/tala. diff --git a/README.md b/README.md new file mode 100644 index 0000000..d5278c4 --- /dev/null +++ b/README.md @@ -0,0 +1,120 @@ +# TALA + +TALA is a diagram layout engine designed specifically for software architecture diagrams, +though it works well in other domains too. TALA is closed-source (for now). This +repository is primarily for installation instructions. You can also use this repository to +report issues, ask questions, and request features. + +To learn more about TALA, please visit +[https://terrastruct.com/tala](https://terrastruct.com/tala). + +To compare TALA with other layout engines, please visit +[https://text-to-diagram.com](https://text-to-diagram.com/?a=d2&layout_a=tala&b=d2&layout_b=dagre&example=chess). + +## Rendering samples + +You can see the `.d2` text for these in [./docs/d2](./docs/d2). Samples are +[generated](./ci/generate_samples.sh) through the CLI. + +|||| +|:-------------------------:|:-------------------------:|:-------------------------:| +|||| + +## Installation + +```sh +curl -fsSL https://d2lang.com/install.sh | sh -s -- --tala --dryrun +# If things look good, install for real. +curl -fsSL https://d2lang.com/install.sh | sh -s -- --tala +``` + +You can also find binaries +[Releases](https://github.com/terarstruct/TALA/releases) page for Linux and MacOS, for +both AMD and ARM. Download the appropriate one for your OS to a directory +in your path. Windows coming soon. + +### Post-install + +Check that it was installed properly: + +```sh +d2 layout tala +``` + +It should print out information about TALA. If not, please see troubleshooting steps. + +### Use TALA + +You are now ready to use TALA to layout your diagrams! Specify that D2 should use TALA by +setting the environment variable `D2_LAYOUT`. + +```sh +D2_LAYOUT=tala d2 in.d2 out.svg +``` + +### Add API token (optional) + +You may skip this step if you are just evaluating. + +If you have an API token, copy and paste it into your environment variables. E.g. + +```bash +export TSTRUCT_TOKEN = "tstruct_..." +``` + +## License keys + +TALA is freely installable and locally runnable for evaluation. You'll need an API token +from your Terrastruct account to run it out of evaluation mode. Alternatively, if you +don't want to create an account, you can purchase a personal license key for TALA that +allows you to run TALA forever with access to updates for 12 months +[here](https://buy.stripe.com/bIYeXL3cT2Lr23e5ko). If you'd like to get the benefits of a +paid Terrastruct account at any time after, your license key will allow that. + +## Troubleshooting + +### TALA not found + +```sh +which d2plugin-tala +``` + +If this does not return a directory, then `d2plugin-tala` is not in your path. + +```sh +echo $PATH +``` + +Please move the downloaded binary to one of those locations. + +### License warning prints even with API token + +In the same terminal that you're running `d2` on, run + +```sh +echo $TSTRUCT_TOKEN +``` + +If it is not found, then your environment variable has not been set in your shell. Make +sure you add it to the appropriate shell config file and `source` it in the running +terminal. + +### Other + +Please open an Issue describing what you're running into and we're happy to help. If you'd +like to remain anonymous/private, feel free to email us at info@terrastruct.com + +## FAQ + +### Does TALA use the internet? + +The TALA plugin do not collect telemetry or use the internet in any way except to ping to +check the status of a license. This is only done when necessary, e.g. if you purchased a +month subscription, TALA will ping at the start of the next month and renew automatically +if the subscription is ongoing. If you purchased a year, it won't ping for a year. The + only data that's sent in these pings is the API token itself. No diagrams or anything + else leaves your computer. + +### Others + +Full FAQ at [https://terrastruct.com/tala](https://terrastruct.com/tala). diff --git a/ci/generate_samples.sh b/ci/generate_samples.sh new file mode 100755 index 0000000..c63434f --- /dev/null +++ b/ci/generate_samples.sh @@ -0,0 +1,18 @@ +#!/bin/sh +set -eu +cd -- "$(dirname "$0")/.." + +THEME_INDEX=0 + +# alternate between cool and warm +themes=(0 100 1 102 4 104 5 105 6) + +for f in ./docs/d2/*.d2 +do + echo "Processing $f" + filename=$(basename -- "$f") + filename="${filename%.*}" + D2_LAYOUT=tala d2 --theme=${themes[$THEME_INDEX]} --debug $f ./docs/assets/${filename}.svg + + let THEME_INDEX=${THEME_INDEX}+1 +done diff --git a/docs/assets/sample_1.svg b/docs/assets/sample_1.svg new file mode 100644 index 0000000..fc2c876 --- /dev/null +++ b/docs/assets/sample_1.svg @@ -0,0 +1,66 @@ + +JobRunner- +start +datetime- +end +datetime- +running_server +string- +threads +int- +manager +JobsManager+ +pipeline +Pipeline+ +setPipeline(Pipeline p) +void+ +kickoff(threads int) +boolJobRunner UIBatchkickoffhaltBatchManager- +num +int- +timeout +int- +pid ++ +getStatus() +Enum+ +getJobs() +Job[]+ +setTimeout(seconds int) +voidSystemdSelenium Ensure aliveRun jobKick offQueue jobs \ No newline at end of file diff --git a/docs/assets/sample_2.svg b/docs/assets/sample_2.svg new file mode 100644 index 0000000..95f0440 --- /dev/null +++ b/docs/assets/sample_2.svg @@ -0,0 +1,31 @@ + +logsAT&T CustomerNetworkAPI ServerCell TowerData ProcessorOnline PortalsatellitestransmitterStorageUI phone logsMake callpersistdisplay access \ No newline at end of file diff --git a/docs/assets/sample_3.svg b/docs/assets/sample_3.svg new file mode 100644 index 0000000..e9cf897 --- /dev/null +++ b/docs/assets/sample_3.svg @@ -0,0 +1,31 @@ + +Server side renderFinal buildUser defined templatesValidation testsRendering Engine APINextJSDataRendered HTMLIngestion moduleData fetching moduleSchema version module Integrate user dataGet version \ No newline at end of file diff --git a/docs/assets/sample_4.svg b/docs/assets/sample_4.svg new file mode 100644 index 0000000..92640ff --- /dev/null +++ b/docs/assets/sample_4.svg @@ -0,0 +1,24 @@ + +paymentAWSData backupData warehouseOn-prem backupsOrchestratorApache AirflowQueue 1Queue 2Queue 1Queue 2Queue 3Queue 4 \ No newline at end of file diff --git a/docs/assets/sample_5.svg b/docs/assets/sample_5.svg new file mode 100644 index 0000000..de3cf96 --- /dev/null +++ b/docs/assets/sample_5.svg @@ -0,0 +1,39 @@ + + + + + + + + + +Offsite TenantAuditorsE335 Data RoomWeb based loggerData for prodQuickbooksIRSClientsbackupsAccountantSecurityJanitorWhitelisted ServerMicrosoft Windows FleetNetwork availabilityaccountantsRouting blockerAdd header tokensbuildApp instancesApp DBsAWS SecretsDocker containers Maintain connection \ No newline at end of file diff --git a/docs/assets/sample_6.svg b/docs/assets/sample_6.svg new file mode 100644 index 0000000..40dd839 --- /dev/null +++ b/docs/assets/sample_6.svg @@ -0,0 +1,24 @@ + +IBM "Espresso" CPUAMD "Latte" GPU2 GB DDR3 RAM "MEM2"RTCIBM PowerPC "Broadway" Core 0IBM PowerPC "Broadway" Core 1IBM PowerPC "Broadway" Core 216 KB ROMMemory & I/O BridgeDRAM Controller32 MB EDRAM "MEM1"512 B SEEPROMSATA IFEXI (Efficient XML Interchange)GXAMD Radeon R7xx "GX2"3 MB 1T-SRAM \ No newline at end of file diff --git a/docs/d2/sample_1.d2 b/docs/d2/sample_1.d2 new file mode 100644 index 0000000..290d308 --- /dev/null +++ b/docs/d2/sample_1.d2 @@ -0,0 +1,39 @@ +runner: JobRunner { + shape: class + + -start: datetime + -end: datetime + -running_server: string + -threads: int + -manager: JobsManager + +pipeline: Pipeline + + +setPipeline(Pipeline p): void + +kickoff(threads int): bool +} + +jobsUI: JobRunner UI { + kickoff + halt +} + +batch: Batch { + manager: BatchManager { + shape: class + -num: int + -timeout: int + -pid + + +getStatus(): Enum + +getJobs(): "Job[]" + +setTimeout(seconds int) + } + systemd: Systemd + selenium: Selenium + + systemd -> manager: Ensure alive + manager -> selenium: Run job +} + +jobsUI -> runner: Kick off +runner -> batch.manager: Queue jobs diff --git a/docs/d2/sample_2.d2 b/docs/d2/sample_2.d2 new file mode 100644 index 0000000..c705db9 --- /dev/null +++ b/docs/d2/sample_2.d2 @@ -0,0 +1,44 @@ +logs: { + shape: page + style.multiple: true +} +user: AT&T Customer {shape: person} +network: Network { + tower: Cell Tower { + satellites: { + shape: stored_data + style.multiple: true + } + transmitter + + satellites -> transmitter + satellites -> transmitter + satellites -> transmitter + } + processor: Data Processor { + storage: Storage { + shape: cylinder + style.multiple: true + } + } + portal: Online Portal { + UI + } + + tower.transmitter -> processor: phone logs +} +server: API Server + +user -> network.tower: Make call +network.processor -> server +network.processor -> server +network.processor -> server + +server -> logs +server -> logs +server -> logs: persist + +server -> network.portal.UI: display +user -> network.portal.UI: access { + style.stroke-dash: 3 +} diff --git a/docs/d2/sample_3.d2 b/docs/d2/sample_3.d2 new file mode 100644 index 0000000..285f5e5 --- /dev/null +++ b/docs/d2/sample_3.d2 @@ -0,0 +1,31 @@ +SSR: Server side render { + templates: User defined templates + + tests: Validation tests + + engine: Rendering Engine\n API { + ingestion: Ingestion module { + shape: hexagon + } + fetch: Data fetching module { + shape: hexagon + } + schema: Schema version module { + shape: hexagon + } + } + next: NextJS + db: Data + + templates -> engine.ingestion + engine.fetch <-> db: Integrate user data + engine.schema <-> db: Get version + + engine <-> tests +} + +build: Final build { + html: Rendered HTML +} + +SSR.engine -> SSR.next -> build.html diff --git a/docs/d2/sample_4.d2 b/docs/d2/sample_4.d2 new file mode 100644 index 0000000..bf89d8f --- /dev/null +++ b/docs/d2/sample_4.d2 @@ -0,0 +1,48 @@ +payment + +AWS { + orchestrator: Orchestrator + airflow: Apache Airflow { + queue1: Queue 1 { + shape: queue + } + queue2: Queue 2 { + shape: queue + } + queue3: Queue 3 { + shape: queue + } + queue4: Queue 4 { + shape: queue + } + } + + orchestrator -> airflow.queue1 + orchestrator -> airflow.queue2 + orchestrator -> airflow.queue3 + orchestrator -> airflow.queue4 +} + +payment -> AWS.orchestrator + +backup: Data backup + +AWS.airflow.queue3 -> backup +AWS.airflow.queue4 -> backup + +data: Data warehouse + +AWS.airflow.queue1 -> data +AWS.airflow.queue2 -> data + +local: On-prem backups { + queue1: Queue 1 { + shape: queue + } + queue2: Queue 2 { + shape: queue + } +} + +backup -> local.queue1 +backup -> local.queue2 diff --git a/docs/d2/sample_5.d2 b/docs/d2/sample_5.d2 new file mode 100644 index 0000000..ae0bdad --- /dev/null +++ b/docs/d2/sample_5.d2 @@ -0,0 +1,73 @@ +tenant: Offsite Tenant { + style.shadow: true + + accountant: Accountant + security: Security + janitor: Janitor +} + +tenant.accountant -> Quickbooks + +auditors: Auditors + +auditors -> Quickbooks +auditors -> IRS +Quickbooks -> Clients + +dataroom: E335 Data Room { + style.shadow: true + style.fill: "#e9edef" + style.stroke-width: 2 + + whitelist: Whitelisted Server { + shape: rectangle + style.stroke-dash: 10 + style.stroke: "#000E3D" + + routing: Routing blocker + headers: Add header tokens + } + + platform: Microsoft Windows Fleet { + style.stroke-dash: 4 + style.stroke: "#000E3D" + build + } + whitelist <-> platform: Maintain connection {style.stroke-width: 4} +} + +auditors -> dataroom.platform.build +auditors -> dataroom.whitelist.routing +tenant.accountants -> dataroom + +logging: Web based logger + +production: Data for prod { + style.shadow: true + + network: Network availability { + style.stroke-dash: 10 + style.stroke: "#000E3D" + + instances: App instances { + style.multiple: true + } + + db: App DBs { + shape: cylinder + } + + secrets: AWS Secrets + + containers: Docker containers + + instances -> db + instances -> secrets + containers -> db + containers -> secrets + } +} + +dataroom.whitelist.routing -> production.network.instances +dataroom.whitelist.headers -> production.network.instances +production.network.instances -> backups diff --git a/docs/d2/sample_6.d2 b/docs/d2/sample_6.d2 new file mode 100644 index 0000000..d31bc12 --- /dev/null +++ b/docs/d2/sample_6.d2 @@ -0,0 +1,49 @@ +ibm: IBM "Espresso" CPU { + core0: IBM PowerPC "Broadway" Core 0 + core1: IBM PowerPC "Broadway" Core 1 + core2: IBM PowerPC "Broadway" Core 2 + + rom: 16 KB ROM + + core0 -- core2 + + rom -> core2 +} + +amd: AMD "Latte" GPU { + mem: Memory & I/O Bridge + dram: DRAM Controller + edram: 32 MB EDRAM "MEM1" + rom: 512 B SEEPROM + + sata: SATA IF + exi: EXI (Efficient XML Interchange) + + gx: GX { + 3 MB 1T-SRAM + } + + radeon: AMD Radeon R7xx "GX2" + + mem -- gx + mem -- radeon + + + rom -- mem + + mem -- sata + mem -- exi + + dram -- sata + dram -- exi +} + +ddr3: 2 GB DDR3 RAM "MEM2" + +amd.mem -- ddr3 +amd.dram -- ddr3 +amd.edram -- ddr3 + +ibm.core1 -- amd.mem + +amd.exi -- RTC