Added Frequently asked questions to each section and moved FAQ's from confluence to the repository
Project: http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/commit/65477127 Tree: http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/tree/65477127 Diff: http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/diff/65477127 Branch: refs/heads/0.4 Commit: 654771271188f2d583b4941be609e9d505f4ffef Parents: 381761b Author: Evan Hughes <ehu...@gmail.com> Authored: Wed Jul 8 21:25:37 2015 +1000 Committer: Evan Hughes <ehu...@gmail.com> Committed: Wed Jul 8 21:25:37 2015 +1000 ---------------------------------------------------------------------- source/api/faq.rst | 19 +++ source/api/index.rst | 2 + source/developer/Resources/agent.png | Bin 0 -> 70281 bytes source/developer/faq.rst | 105 ++++++++++++++++ source/developer/index.rst | 1 + source/documentation/faq.rst | 19 +++ source/documentation/index.rst | 1 + source/manual/Resources/deleting-wave.png | Bin 0 -> 37086 bytes source/manual/faq.rst | 167 +++++++++++++++++++++++++ source/manual/index.rst | 4 +- source/protocol/faq.rst | 20 +++ source/protocol/index.rst | 1 + 12 files changed, 337 insertions(+), 2 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/blob/65477127/source/api/faq.rst ---------------------------------------------------------------------- diff --git a/source/api/faq.rst b/source/api/faq.rst new file mode 100644 index 0000000..4cd4b17 --- /dev/null +++ b/source/api/faq.rst @@ -0,0 +1,19 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +FAQ +=== http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/blob/65477127/source/api/index.rst ---------------------------------------------------------------------- diff --git a/source/api/index.rst b/source/api/index.rst index dc74a31..302e987 100644 --- a/source/api/index.rst +++ b/source/api/index.rst @@ -25,3 +25,5 @@ Contents: .. toctree:: :maxdepth: 2 + + faq http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/blob/65477127/source/developer/Resources/agent.png ---------------------------------------------------------------------- diff --git a/source/developer/Resources/agent.png b/source/developer/Resources/agent.png new file mode 100644 index 0000000..9b2cd2d Binary files /dev/null and b/source/developer/Resources/agent.png differ http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/blob/65477127/source/developer/faq.rst ---------------------------------------------------------------------- diff --git a/source/developer/faq.rst b/source/developer/faq.rst new file mode 100644 index 0000000..4fa896e --- /dev/null +++ b/source/developer/faq.rst @@ -0,0 +1,105 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +FAQ's +===== + +.. toctree:: + + +Code +---- + +Where are the binaries? +^^^^^^^^^^^^^^^^^^^^^^^ + +The design of the server is moving very quickly with almost daily updates to the source code in the repository so any +binaries would be very quickly out of date. We've worked hard to make the server have as few dependencies as possible, +you should only need to install Ant above and beyond the required Java 6 SDK. + +Does it run on App Engine? TODO: is this still true? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +It's not in our medium-term plan to have Wave in a Box run on App Engine. + +Does it support the embed API? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +There is no plan to support embedding in the open source plan, but it should be fairly straightforward for a developer +to modify the code so that there is an output of the client that includes only the wave panel. (The Google Wave embed +API basically did that-- just hid all the other panels). + +You can see a basic Embed API JS here: http://wave-api.appspot.com/public/embed.js + +How similar will robots be to robots suitable for Google Wave? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +We hope to have the protocols be quite similar, and if there are changes, they will be made to improve the protocol for +the better. If you plan on running Wave-in-a-Box when available and want to develop robots in preparation for that, +then we'd recommend developing them according to the current specification. + +Does it include the spell-checking or linking agent? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The code does not include the spell-checking agent ("Spelly") and will probably not include the linking agent ("Linky"). + +Protocol & Data Models +---------------------- + +How do I define ACLs for a Wave? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +As of right now the Access Control to a wavelet is simply boolean, that is, you either have full read-write access to a +wavelet, or you have no access to a wavelet. There have been recurring questions about finer grained controls, and while +ACLs are currently under discussion, at this point we don't have anything solid enough to put forward as a proposal. + +What is the client-server protocol? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The focus of our open source and protocol work at this point is on the federation protocol, which is critical for +getting inter-operable server implementations, that is, for allowing many other people to build Wave servers and have +them interop with each other and with the Google Wave server. We have definitely heard the requests for defining a +client-server protocol, but at this time the team doesn't have the time to put into such an effort. + +If you are interested in working on the client-server protocol we are happy to host that discussion here, and the +client-server protocol as implemented in the open source server would be a fine place to start. + +What's the XML schema for waves? Why isn't it HTML5? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Wave documents differ from XML in two ways: + +* they have a much smaller set of allowed node types, only elements and text +* they include stand-off key/value annotations, which are not part of XML + +The primary reason we don't use a highly structured format like HTML is that such a format does not have desirable +properties under operational transformation, when multiple clients edit the same document concurrently. While HTML +attempts to separate semantic content from presentation, waves also need to be concerned with the operational +transformation layer underneath, and HTML makes OT (Operational Transforms) difficult if not impossible. Wave +documents do have schemas, however. These are currently defined in the org.waveprotocol.wave.model.schema package. + +What about attachments? +^^^^^^^^^^^^^^^^^^^^^^^ +Attachments will eventually be rolled into the federation specification. The current whitepaper describes the design of +existing non-federated attachment system and is a good place to start learning about attachments. + +What is the difference between an Agent and a Robot? +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +This diagram shows the relationship between agents and robots: + +.. image:: Resources/agent.png + +An agent runs on the server and performs services there. A robot proxy is just an agent that delegates out actions to +robot servers over HTTP and acts on the robot servers behalf. The example code contains a simple agent called Echoey. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/blob/65477127/source/developer/index.rst ---------------------------------------------------------------------- diff --git a/source/developer/index.rst b/source/developer/index.rst index e2b93a0..56bf106 100644 --- a/source/developer/index.rst +++ b/source/developer/index.rst @@ -23,6 +23,7 @@ Apache Wave (incubating)'s Developer documentation! :maxdepth: 2 :includehidden: + faq Contributing/index Code Walk/index Tutorials/index http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/blob/65477127/source/documentation/faq.rst ---------------------------------------------------------------------- diff --git a/source/documentation/faq.rst b/source/documentation/faq.rst new file mode 100644 index 0000000..4cd4b17 --- /dev/null +++ b/source/documentation/faq.rst @@ -0,0 +1,19 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +FAQ +=== http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/blob/65477127/source/documentation/index.rst ---------------------------------------------------------------------- diff --git a/source/documentation/index.rst b/source/documentation/index.rst index 8e735a0..19ee14f 100644 --- a/source/documentation/index.rst +++ b/source/documentation/index.rst @@ -24,6 +24,7 @@ Apache Wave (incubating)'s documentation :maxdepth: 2 :includehidden: + faq Introduction/index About/index Installing/index http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/blob/65477127/source/manual/Resources/deleting-wave.png ---------------------------------------------------------------------- diff --git a/source/manual/Resources/deleting-wave.png b/source/manual/Resources/deleting-wave.png new file mode 100644 index 0000000..760d874 Binary files /dev/null and b/source/manual/Resources/deleting-wave.png differ http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/blob/65477127/source/manual/faq.rst ---------------------------------------------------------------------- diff --git a/source/manual/faq.rst b/source/manual/faq.rst new file mode 100644 index 0000000..0c6d2dc --- /dev/null +++ b/source/manual/faq.rst @@ -0,0 +1,167 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +FAQ's +===== + +.. toctree:: + +Administration Tips +------------------- + +This page contains tips for administrating a Wave in the Box instance, adapted from `bash.vi`_ + +.. _bash.vi: http://bashvi.tumblr.com/post/41642537267/some-apache-wave-administration-tips + +TODO: + +* Write instructions for windows as well +* Add pages with instructions for run-export etc + +Changing Your Password +^^^^^^^^^^^^^^^^^^^^^^ +Changing your password is a simple operation which currently requires the passwd bot. + +1. Add the bot "passwd-bot" to a new, private wave +2. Type passwd <current password> <new password> <enter> + +To see all the options for the passwd-bot type passwd -help <enter> + +.. _Adding-an-Administrator-Account: + +Adding an Administrator Account +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +By default, no admin account is set. You can define the admin account by changing the + +<property name=âadmin_userâ value=â@${wave_server_domain}â /> + +variable in the server-config.xml file and regenerating the config with + +ant -f server-config.xml + +All you have to do is put the name of the account that should have administrator privileges in front of the @ sign. + +Changing Users Passwords +^^^^^^^^^^^^^^^^^^^^^^^^ +The admin account can change the password of other users. The process is very similar to changing oneâs own password: + +1. Log in with your Admin user (see :ref:`Adding-an-Administrator-Account`) +2. Create a new, private wave +3. Add the bot "passwdadmin-bot" to the wave +4. type passwdadmin <username> <new_password> to change a users password + +To see the help for the passwdadmin-bot type passwdadmin -help <enter> + +Adding a User when registration is disabled +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The admin account can register new users event when registration is disabled on the server: + +1. Log in with your Admin user (see :ref:`Adding-an-Administrator-Account`) +2. Create a new, private wave +3. Add the bot "registration-bot" to the wave +4. type register <username> <password> to create the user with a particular password + +To see the help for the registration-bot type register -help <enter>. + +Deleting a User +^^^^^^^^^^^^^^^ + +1. SSH into your Wave Server +2. Stop Wave TODO: How to stop wave server? +3. Change into the Wave installation directory and then /_accounts/ +4. Each file in this folder represents a user - labeled <username>@<yourdomain>.account +5. Remove the file corresponding to the correct user (rm does this on linux systems) +6. Start the Wave server again + +Deleting Empty Waves +^^^^^^^^^^^^^^^^^^^^ +Sometimes weird, empty waves will appears at the bottom of your inbox. The instructions that follow are potentially +unsafe and should only be used if you're sure you know what you are doing. + +.. image:: Resources/deleting-wave.png + +1. SSH into your wave server +2. Stop Wave +3. Change into the Wave installation directory and then /_deltas +4. ls will show a number of subdirectories with alphanumeric names. Each one of these represents a wave. +5. du -h * will show the size of each of these directories +6. The smallest ones (~20K) are likely to be the empty waves (back them up with tar cfv ../backup.tar <directory1> + <directory2>) +7. Delete these small directories +8. Start the Wave Server + +Log back in and wait for Wave index to be regenerated, if the incorrect waves are deleted restore them from the backups +you created. + +Once again, this procedure is potentially unsafe and you should only attempt it if you are confident and have a backup. + +Exporting Waves +^^^^^^^^^^^^^^^ +Wave comes with means to export all of a users waves and import them into another server or just store them for backup +purposes. This process doesn't have to be performed on the server itself, any user can export their waves allowing them +to make their own personal backups. + +1. Download and compile Apache Wave from `source`_ +2. In the root directory there is a run-export.sh file, make it executable using chmod +x run-export.sh +3. Run the script by executing `./run-export.sh`_ to see available parameters and access help + +For further information on run-export.sh see: run-export.sh + +.. _source: http://incubator.apache.org/wave/source-code.html +.. _./run-export.sh: https://cwiki.apache.org/confluence/display/WAVE/run-export.sh + +Add your CA to Java +^^^^^^^^^^^^^^^^^^^ +Taken and adapted from: `Adding a certificate authority to the Java runtime`_ + +If your wave server is running with SSL and you signed your ssl certificate with your own CA, you should add that CA to +Javaâs trusted list of CAs. Otherwise the internal bots, such as the passwd bot, and scripts, such as the export script, +might not work. + +Before you start you will need your CAs public certificate which should be in .pem format. + +Type the following command: keytool -import -trustcacerts -file <path to CA key> -alias honet -keystore +$JAVA_HOME/jre/lib/security/cacerts + +It will then ask you for a password, the default is: changeit + +.. _Adding a certificate authority to the Java runtime: + http://www.mikepilat.com/blog/2011/05/adding-a-certificate-authority-to-the-java-runtime/ + +Changing your Avatar +^^^^^^^^^^^^^^^^^^^^ +The avatars used in wave are served from `Gravatar`_. This server creates an image based on the hash of an email address +. For Wave the address <username>@<domain> is being hashed and sent to Gravatar for the Avatar creation. You can then +sign up to Gravatar to change the image. This will cause your avatar to instantly change on all sites that use Gravatar. + +After the initial creation you are able to add more emails to the Gravator, however Gravatar will send a confirmation +email to each of these addresses with a link to be clicked. This becomes an issue because a wave adress s not an email +address. This can be solved by setting up an Email server temporarily to receive the confirmation links. + +On Debian this is as simple as running apt-get install postfix. + +During the installation, youâll be asked for some things. Tell it to run on the internet (and not just locally). It is +very important that you tell it your waves domain name when asked for it. You should have a functioning email server now +running. To make sure it is working we add a unix user with the same name as your wave account: useradd -m -d +/home/<username> -s /bin/bash <username> + +Now go to Gravatar, click on âMy accountâ and then âAdd an Email Addressâ. Type in <username>@<wavedomain>. The email +will appear in /var/mail/<username>. Use cat, less or another text editor to view the email. + +.. _Gravatar: https://cwiki.apache.org/confluence/display/WAVE/Administration+Tips# http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/blob/65477127/source/manual/index.rst ---------------------------------------------------------------------- diff --git a/source/manual/index.rst b/source/manual/index.rst index 8d0dd43..edb3b5f 100644 --- a/source/manual/index.rst +++ b/source/manual/index.rst @@ -19,7 +19,7 @@ Apache Wave (incubating)'s User Manual ====================================== -Contents: - .. toctree:: :maxdepth: 2 + + faq \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/blob/65477127/source/protocol/faq.rst ---------------------------------------------------------------------- diff --git a/source/protocol/faq.rst b/source/protocol/faq.rst new file mode 100644 index 0000000..e58e085 --- /dev/null +++ b/source/protocol/faq.rst @@ -0,0 +1,20 @@ +7.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + +.. http://www.apache.org/licenses/LICENSE-2.0 + +.. Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +FAQ +=== + http://git-wip-us.apache.org/repos/asf/incubator-wave-docs/blob/65477127/source/protocol/index.rst ---------------------------------------------------------------------- diff --git a/source/protocol/index.rst b/source/protocol/index.rst index d653299..6518b06 100644 --- a/source/protocol/index.rst +++ b/source/protocol/index.rst @@ -29,6 +29,7 @@ high level technical information about how Apache Wave comes together. .. toctree:: :maxdepth: 1 + faq operational-transform/operational-transform google-wave-architecture/google-wave-architecture client-server-protocol/client-server-protocol
