incubator-wave-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From a.@apache.org
Subject [3/4] incubator-wave-docs git commit: Added Frequently asked questions to each section and moved FAQ's from confluence to the repository
Date Sat, 22 Aug 2015 19:49:53 GMT
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 <ehugh1@gmail.com>
Authored: Wed Jul 8 21:25:37 2015 +1000
Committer: Evan Hughes <ehugh1@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


Mime
View raw message